@venizia/ignis-docs 0.0.1-1

package/wiki/references/base/dependency-injection.md

@@ -0,0 +1,83 @@
+# Deep Dive: Dependency Injection
+
+Technical reference for the DI system in Ignis - managing resource lifecycles and dependency resolution.
+
+**Files:**
+- `packages/core/src/helpers/inversion/container.ts`
+- `packages/core/src/base/metadata/injectors.ts`
+- `packages/helpers/src/helpers/inversion/registry.ts`
+
+## Quick Reference
+
+| Component | Purpose | Key Methods |
+|-----------|---------|-------------|
+| **Container** | DI registry managing resource lifecycles | `bind()`, `get()`, `instantiate()`, `findByTag()` |
+| **Binding** | Single registered dependency configuration | `toClass()`, `toValue()`, `toProvider()`, `setScope()` |
+| **@inject** | Decorator marking injection points | Applied to constructor parameters/properties |
+| **MetadataRegistry** | Stores decorator metadata | Singleton accessed via `getInstance()` |
+
+## `Container` Class
+
+Heart of the DI system - registry managing all application resources.
+
+**File:** `packages/core/src/helpers/inversion/container.ts`
+
+### Key Methods
+
+| Method | Description |
+| :--- | :--- |
+| **`bind<T>({ key })`** | Starts a new binding for a given key. It returns a `Binding` instance that you can use to configure the dependency. |
+| **`get<T>({ key, isOptional })`** | Retrieves a dependency from the container. The `key` can be a string, a symbol, or an object like `{ namespace: 'services', key: 'MyService' }`. If the dependency is not found and `isOptional` is `false` (the default), it will throw an error. |
+| **`instantiate<T>(cls)`** | Creates a new instance of a class, automatically injecting any dependencies specified in its constructor or on its properties. This is the method the container uses internally to create your controllers, services, etc. |
+| **`findByTag({ tag })`** | Finds all bindings that have been tagged with a specific tag (e.g., `'controllers'`, `'components'`). This is used by the application to discover and initialize all registered resources of a certain type. |
+
+## `Binding` Class
+
+A `Binding` represents a single registered dependency in the container. It's a fluent API that allows you to specify *how* a dependency should be created and managed.
+
+-   **File:** `packages/core/src/helpers/inversion/container.ts`
+
+### Configuration Methods
+
+| Method | Description |
+| :--- | :--- |
+| **`toClass(MyClass)`** | Binds the key to a class. The container will instantiate this class (and resolve its dependencies) when the key is requested. |
+| **`toValue(someValue)`** | Binds the key to a constant value (e.g., a configuration object, a string, a number). |
+| **`toProvider(MyProvider)`**| Binds the key to a provider class or function. This is for dependencies that require complex creation logic. |
+| **`setScope(scope)`** | Sets the lifecycle scope of the binding. See "Binding Scopes" below. |
+
+### Binding Scopes
+
+| Scope | Description |
+| :--- | :--- |
+| **`BindingScopes.TRANSIENT`** | (Default) A new instance of the dependency is created every time it is injected or requested from the container. |
+| **`BindingScopes.SINGLETON`** | A single instance is created the first time it is requested, and that same instance is reused for all subsequent requests. DataSources and Components are typically singletons. |
+
+## `@inject` Decorator
+
+The `@inject` decorator is used to mark where dependencies should be injected.
+
+-   **File:** `packages/core/src/base/metadata/injectors.ts`
+
+### How It Works
+
+1.  When you apply the `@inject` decorator to a constructor parameter or a class property, it uses `Reflect.metadata` to attach metadata to the class.
+2.  The metadata includes the **binding key** of the dependency to be injected.
+3.  When the `container.instantiate(MyClass)` method is called, it reads this metadata.
+4.  It then calls `container.get({ key })` for each decorated parameter/property to resolve the dependency.
+5.  Finally, it creates the instance of `MyClass`, passing the resolved dependencies to the constructor or setting them on the instance properties.
+
+This entire process is managed by the framework when your application starts up, ensuring that all your registered classes are created with their required dependencies.
+
+## `MetadataRegistry`
+
+The `MetadataRegistry` is a crucial part of the DI and routing systems. It's a singleton class responsible for storing and retrieving all the metadata attached by decorators like `@inject`, `@controller`, `@get`, etc.
+
+-   **File:** `packages/helpers/src/helpers/inversion/registry.ts`
+
+### Role in DI
+
+-   When you use a decorator (e.g., `@inject`), it calls a method on the `MetadataRegistry.getInstance()` to store information about the injection (like the binding key and target property/parameter).
+-   When the `Container` instantiates a class, it queries the `MetadataRegistry` to find out which dependencies need to be injected and where.
+
+You typically won't interact with the `MetadataRegistry` directly, but it's the underlying mechanism that makes the decorator-based DI and routing systems work seamlessly.

package/wiki/references/base/models.md

@@ -0,0 +1,104 @@
+# Deep Dive: Models and Enrichers
+
+Technical reference for model architecture and schema enrichers in Ignis.
+
+**Files:**
+- `packages/core/src/base/models/base.ts`
+- `packages/core/src/base/models/enrichers/*.ts`
+
+## Quick Reference
+
+| Component | Purpose | Key Features |
+|-----------|---------|--------------|
+| **BaseEntity** | Wraps Drizzle schema | Schema encapsulation, Zod generation, `toObject()`/`toJSON()` |
+| **Schema Enrichers** | Add common columns to tables | `generateIdColumnDefs()`, `generateTzColumnDefs()`, etc. |
+
+## `BaseEntity` Class
+
+Fundamental building block wrapping a Drizzle ORM schema.
+
+**File:** `packages/core/src/base/models/base.ts`
+
+### Purpose
+
+| Feature | Description |
+|---------|-------------|
+| **Schema Encapsulation** | Holds Drizzle `pgTable` schema for consistent repository access |
+| **Metadata** | Works with `@model` decorator to mark database entities |
+| **Schema Generation** | Uses `drizzle-zod` to generate Zod schemas (`SELECT`, `CREATE`, `UPDATE`) |
+| **Convenience** | Includes `toObject()` and `toJSON()` methods |
+
+### Class Definition
+
+```typescript
+import { createSchemaFactory } from 'drizzle-zod';
+import { BaseHelper } from '../helpers';
+import { SchemaTypes, TSchemaType, TTableSchemaWithId } from './common';
+
+export class BaseEntity<Schema extends TTableSchemaWithId = TTableSchemaWithId> extends BaseHelper {
+  name: string;
+  schema: Schema;
+  schemaFactory: ReturnType<typeof createSchemaFactory>;
+
+  constructor(opts: { name: string; schema: Schema }) {
+    super({ scope: opts.name });
+    this.name = opts.name;
+    this.schema = opts.schema;
+    this.schemaFactory = createSchemaFactory();
+  }
+
+  getSchema(opts: { type: TSchemaType }) {
+    switch (opts.type) {
+      case SchemaTypes.CREATE: {
+        return this.schemaFactory.createInsertSchema(this.schema);
+      }
+      case SchemaTypes.UPDATE: {
+        return this.schemaFactory.createUpdateSchema(this.schema);
+      }
+      case SchemaTypes.SELECT: {
+        return this.schemaFactory.createSelectSchema(this.schema);
+      }
+      default: {
+        throw getError({
+          message: `[getSchema] Invalid schema type | type: ${opts.type} | valid: ${[SchemaTypes.SELECT, SchemaTypes.UPDATE, SchemaTypes.CREATE]}`,
+        });
+      }
+    }
+  }
+}
+```
+
+When you define a model in your application, you extend `BaseEntity`, passing your Drizzle table schema to the `super` constructor.
+
+## Schema Enrichers
+
+Enrichers are helper functions located in `packages/core/src/base/models/enrichers/` that return an object of Drizzle ORM column definitions. They are designed to be spread into a `pgTable` definition to quickly add common, standardized fields to your models.
+
+### Available Enrichers
+
+| Enricher Function | Purpose |
+| :--- | :--- |
+| **`generateIdColumnDefs`** | Adds a primary key `id` column (string UUID or numeric serial). |
+| **`generateTzColumnDefs`** | Adds `createdAt` and `modifiedAt` timestamp columns with timezone support. |
+| **`generateUserAuditColumnDefs`** | Adds `createdBy` and `modifiedBy` columns to track user audit information. |
+| **`generateDataTypeColumnDefs`** | Adds generic data type columns (`dataType`, `nValue`, `tValue`, `bValue`, `jValue`, `boValue`) for flexible data storage. |
+| **`generatePrincipalColumnDefs`** | Adds polymorphic fields for associating with different principal types. |
+| **`extraUserColumns`** (from `components/auth/models/entities/user.model.ts`) | Adds common fields for a user model, such as `realm`, `status`, `type`, `activatedAt`, `lastLoginAt`, and `parentId`. |
+
+### Example Usage
+
+```typescript
+import { pgTable, text } from 'drizzle-orm/pg-core';
+import {
+  generateIdColumnDefs,
+  generateTzColumnDefs,
+  generateUserAuditColumnDefs,
+} from '@venizia/ignis';
+
+export const myTable = pgTable('MyTable', {
+  ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+  ...generateTzColumnDefs(),
+  ...generateUserAuditColumnDefs({ created: { dataType: 'string' }, modified: { dataType: 'string' } }),
+  name: text('name').notNull(),
+});
+```

package/wiki/references/base/repositories.md

@@ -0,0 +1,118 @@
+# Deep Dive: Repositories
+
+Technical reference for repository classes - the data access layer in Ignis.
+
+**Files:** `packages/core/src/base/repositories/core/*.ts`
+
+## Quick Reference
+
+| Class | Capabilities | Use Case |
+|-------|--------------|----------|
+| **AbstractRepository** | Base class with properties | Extend for custom repositories |
+| **ReadableRepository** | Read-only operations | Views, external tables |
+| **PersistableRepository** | Read + Write operations | Rarely used directly |
+| **DefaultCRUDRepository** | Full CRUD operations | Standard data tables ✅ |
+
+## `AbstractRepository`
+
+Base class for all repositories - sets up fundamental properties and dependencies for data access.
+
+**File:** `packages/core/src/base/repositories/core/base.ts`
+
+### Key Properties
+
+-   `entity` (`BaseEntity`): An instance of the model class associated with this repository. It provides access to the Drizzle schema.
+-   `dataSource` (`IDataSource`): The datasource instance injected into the repository, which holds the database connection.
+-   `connector`: A getter that provides direct access to the Drizzle ORM instance from the datasource.
+-   `filterBuilder` (`DrizzleFilterBuilder`): An instance of the filter builder responsible for converting `Ignis`'s filter objects into Drizzle-compatible query options.
+-   `relations` (`{ [relationName: string]: TRelationConfig }`): A map of relation configurations defined for the entity.
+
+### Abstract Methods
+
+`AbstractRepository` defines the method signatures for standard CRUD operations that concrete repository classes must implement:
+- `count()`
+- `existsWith()`
+- `find()`
+- `findOne()`
+- `findById()`
+- `create()`
+- `updateById()`
+- `deleteById()`
+- (and `...All` variants)
+
+## `ReadableRepository`
+
+The `ReadableRepository` provides a **read-only** implementation of the repository pattern. It is ideal for data sources that should not be modified, such as views or tables from an external system.
+
+-   **File:** `packages/core/src/base/repositories/core/readable.ts`
+
+### Implemented Methods
+
+`ReadableRepository` provides concrete implementations for all read operations:
+
+-   **`find(opts)`**: Returns an array of entities matching the filter.
+-   **`findOne(opts)`**: Returns the first entity matching the filter.
+-   **`findById(opts)`**: A convenience method that calls `findOne` with an ID-based `where` clause.
+-   **`count(opts)`**: Returns the number of entities matching the `where` clause.
+-   **`existsWith(opts)`**: Returns `true` if at least one entity matches the `where` clause.
+
+### Write Operations
+
+`ReadableRepository` throws a "NOT ALLOWED" error for all write operations (`create`, `update`, `delete`).
+
+## `PersistableRepository`
+
+The `PersistableRepository` extends `ReadableRepository` and adds **write operations**. It provides the core logic for creating, updating, and deleting records.
+
+-   **File:** `packages/core/src/base/repositories/core/persistable.ts`
+
+### Implemented Methods
+
+-   `create(opts)`
+-   `createAll(opts)`
+-   `updateById(opts)`
+-   `updateAll(opts)`
+-   `deleteById(opts)`
+-   `deleteAll(opts)`
+
+You will typically not use this class directly, but rather the `DefaultCRUDRepository`.
+
+## `DefaultCRUDRepository`
+
+This is the primary class you should extend for repositories that require full **Create, Read, Update, and Delete (CRUD)** capabilities. It extends `PersistableRepository` and serves as the standard, full-featured repository implementation.
+
+-   **File:** `packages/core/src/base/repositories/core/default-crud.ts`
+
+### Example Implementation
+
+```typescript
+// src/repositories/configuration.repository.ts
+import {
+  Configuration,
+  configurationRelations,
+  TConfigurationSchema,
+} from '@/models/entities';
+import { IDataSource, inject, repository, DefaultCRUDRepository } from '@venizia/ignis';
+
+// Decorator to mark this class as a repository for DI
+@repository({})
+export class ConfigurationRepository extends DefaultCRUDRepository<TConfigurationSchema> {
+  constructor(
+    // Inject the configured datasource
+    @inject({ key: 'datasources.PostgresDataSource' }) dataSource: IDataSource,
+  ) {
+    // Pass the datasource, the model's Entity class, and the relations definitions to the super constructor
+    super({ dataSource, entityClass: Configuration, relations: configurationRelations.definitions });
+  }
+
+  // You can add custom data access methods here
+  async findByCode(code: string): Promise<Configuration | undefined> {
+    // 'this.connector' gives you direct access to the Drizzle instance
+    const result = await this.connector.query.Configuration.findFirst({
+      where: (table, { eq }) => eq(table.code, code)
+    });
+    return result;
+  }
+}
+```
+This architecture provides a clean and powerful abstraction for data access, separating the "how" of data fetching (Drizzle logic) from the "what" of business logic (services).

package/wiki/references/base/services.md

@@ -0,0 +1,97 @@
+# Deep Dive: Services
+
+Technical reference for `BaseService` - the foundation for business logic layers in Ignis.
+
+**File:** `packages/core/src/base/services/base.ts`
+
+## Quick Reference
+
+| Feature | Benefit |
+|---------|---------|
+| **Extends `BaseHelper`** | Auto-configured scoped logger (`this.logger`) |
+| **DI Integration** | Fits into framework's dependency injection system |
+| **Business Logic Layer** | Bridge between Controllers and Repositories |
+
+## `BaseService` Class
+
+Abstract class that all application services should extend.
+
+### Key Features
+
+| Feature | Description |
+| :--- | :--- |
+| **Standardization** | Common base for all services, fits framework architecture |
+| **Logging** | Extends `BaseHelper` - auto-configured logger at `this.logger` (scope = class name) |
+| **Clarity** | Signals the class contains business logic |
+
+### Class Definition
+
+The implementation is straightforward:
+
+```typescript
+import { BaseHelper } from '../helpers';
+import { IService } from './types';
+
+export abstract class BaseService extends BaseHelper implements IService {
+  constructor(opts: { scope: string }) {
+    super({ scope: opts.scope });
+  }
+}
+```
+
+## How Services Fit into the Architecture
+
+Services are the core of your application's logic. They act as a bridge between the presentation layer (Controllers) and the data access layer (Repositories).
+
+### Typical Service Flow
+
+1.  **Instantiated by DI Container**: When the application starts, the DI container creates instances of your services.
+2.  **Dependencies Injected**: The service's constructor receives instances of any repositories or other services it depends on.
+3.  **Called by a Controller**: An HTTP request comes into a controller, which then calls a method on a service to handle the business logic for that request.
+4.  **Orchestrates Logic**: The service method executes the business logic. This may involve:
+    -   Validating input data.
+    -   Calling one or more repository methods to fetch or save data.
+    -   Calling other services to perform related tasks.
+    -   Performing calculations or data transformations.
+5.  **Returns Data**: The service returns the result of the operation back to the controller, which then formats it into an HTTP response.
+
+### Example
+
+```typescript
+import { BaseService, inject } from '@venizia/ignis';
+import { UserRepository } from '../repositories/user.repository';
+import { TUser } from '../models/entities';
+
+// 1. Service is decorated with `@injectable` (or registered via `app.service()`)
+@injectable()
+export class UserService extends BaseService {
+  // 2. Dependencies (like UserRepository) are injected
+  constructor(
+    @inject({ key: 'repositories.UserRepository' })
+    private userRepository: UserRepository,
+  ) {
+    super({ scope: UserService.name });
+  }
+
+  // 3. Method is called by a controller
+  async getUserProfile(userId: string): Promise<Partial<TUser>> {
+    this.logger.info(`Fetching profile for user ${userId}`);
+
+    // 4. Orchestrates logic: calls the repository
+    const user = await this.userRepository.findById({ id: userId });
+
+    if (!user) {
+      throw new Error('User not found');
+    }
+
+    // 5. Returns transformed data
+    return {
+      id: user.id,
+      name: user.name, // Assuming a 'name' field exists
+      email: user.email,
+    };
+  }
+}
+```
+
+By adhering to this pattern, you keep your code organized, testable, and maintainable. You can easily test `UserService` by providing a mock `UserRepository` without needing a real database connection.

package/wiki/references/components/authentication.md

@@ -0,0 +1,224 @@
+# Authentication Component
+
+JWT-based authentication and authorization system for Ignis applications.
+
+## Quick Reference
+
+| Component | Purpose |
+|-----------|---------|
+| **AuthenticateComponent** | Main component registering auth services and controllers |
+| **AuthenticationStrategyRegistry** | Singleton managing available auth strategies |
+| **JWTAuthenticationStrategy** | JWT verification using `JWTTokenService` |
+| **JWTTokenService** | Generate, verify, encrypt/decrypt JWT tokens |
+| **IAuthService** | Interface for custom auth implementation (sign-in, sign-up) |
+
+### Key Environment Variables
+
+| Variable | Purpose | Required |
+|----------|---------|----------|
+| `APP_ENV_APPLICATION_SECRET` | Encrypt JWT payload | ✅ Yes |
+| `APP_ENV_JWT_SECRET` | Sign and verify JWT signature | ✅ Yes |
+| `APP_ENV_JWT_EXPIRES_IN` | Token expiration (seconds) | Optional |
+
+## Architecture Components
+
+-   **`AuthenticateComponent`**: Registers all necessary services and controllers
+-   **`AuthenticationStrategyRegistry`**: Singleton managing authentication strategies
+-   **`JWTAuthenticationStrategy`**: JWT strategy implementation using `JWTTokenService`
+-   **`JWTTokenService`**: Generates, verifies, encrypts/decrypts JWT payloads
+-   **Protected Routes**: Use `authStrategies` in route configs to secure endpoints
+
+## Implementation Details
+
+### Tech Stack
+
+-   **Hono**
+-   **`jose`:** For JWT signing, verification, and encryption.
+-   **`@venizia/ignis`**: The core framework.
+
+### Configuration
+
+Configure the authentication feature using environment variables:
+
+-   `APP_ENV_APPLICATION_SECRET`: A secret for encrypting the JWT payload.
+-   `APP_ENV_JWT_SECRET`: The secret for signing and verifying the JWT signature.
+-   `APP_ENV_JWT_EXPIRES_IN`: The JWT expiration time in seconds.
+
+::: danger SECURITY NOTE
+Both `APP_ENV_APPLICATION_SECRET` and `APP_ENV_JWT_SECRET` are **mandatory**. For security purposes, you must set these to strong, unique secret values. The application will fail to start if these environment variables are missing or left empty.
+:::
+
+**Example `.env` file:**
+
+```
+APP_ENV_APPLICATION_SECRET=your-strong-application-secret
+APP_ENV_JWT_SECRET=your-strong-jwt-secret
+APP_ENV_JWT_EXPIRES_IN=86400
+```
+
+### Code Samples
+
+#### 1. Registering the Authentication Component
+
+In `src/application.ts`, register the `AuthenticateComponent` and the `JWTAuthenticationStrategy`. You also need to provide an `AuthenticationService`.
+
+```typescript
+// src/application.ts
+import {
+  AuthenticateComponent,
+  Authentication,
+  AuthenticationStrategyRegistry,
+  JWTAuthenticationStrategy,
+  BaseApplication,
+  ValueOrPromise,
+} from '@venizia/ignis';
+import { AuthenticationService } from './services'; // Your custom auth service
+
+export class Application extends BaseApplication {
+  // ...
+
+  registerAuth() {
+    this.service(AuthenticationService);
+    this.component(AuthenticateComponent);
+    AuthenticationStrategyRegistry.getInstance().register({
+      container: this,
+      name: Authentication.STRATEGY_JWT,
+      strategy: JWTAuthenticationStrategy,
+    });
+  }
+
+  preConfigure(): ValueOrPromise<void> {
+    // ...
+    this.registerAuth();
+    // ...
+  }
+}
+```
+
+#### 2. Implementing an AuthenticationService
+
+The `AuthenticateComponent` depends on a service that implements the `IAuthService` interface. You need to provide your own implementation for this service, which will contain your application's specific logic for user authentication.
+
+Here is a minimal example of what this service might look like:
+
+```typescript
+// src/services/authentication.service.ts
+import {
+  BaseService,
+  inject,
+  IAuthService,
+  IJWTTokenPayload,
+  JWTTokenService,
+  TSignInRequest,
+} from '@venizia/ignis';
+import { Context } from 'hono';
+
+export class AuthenticationService extends BaseService implements IAuthService {
+  constructor(
+    @inject({ key: 'services.JWTTokenService' }) private jwtService: JWTTokenService,
+  ) {
+    super({ scope: AuthenticationService.name });
+  }
+
+  async signIn(context: Context, opts: TSignInRequest): Promise<{ token: string }> {
+    const { identifier, credential } = opts;
+
+    // --- Your custom logic here ---
+    // 1. Find the user by identifier (e.g., username or email).
+    // 2. Verify the credential (e.g., check the password).
+    // 3. If valid, create a JWT payload.
+    const user = { id: 'user-id-from-db', roles: [] }; // Dummy user
+
+    if (identifier.value !== 'test_username' || credential.value !== 'test_password') {
+      throw new Error('Invalid credentials');
+    }
+    // --- End of custom logic ---
+
+    const payload: IJWTTokenPayload = {
+      userId: user.id,
+      roles: user.roles,
+      // Add any other data you want in the token
+    };
+
+    const token = await this.jwtService.generate({ payload });
+    return { token };
+  }
+
+  async signUp(context: Context, opts: any): Promise<any> {
+    // Implement your sign-up logic
+    throw new Error('Method not implemented.');
+  }
+
+  async changePassword(context: Context, opts: any): Promise<any> {
+    // Implement your change password logic
+    throw new Error('Method not implemented.');
+  }
+}
+```
+
+This service is then registered in `application.ts` as shown in the previous step. It injects the `JWTTokenService` (provided by the `AuthenticateComponent`) to generate a token upon successful sign-in.
+
+#### 3. Securing Routes
+
+In your controllers, use decorator-based routing (`@get`, `@post`, etc.) with the `authStrategies` property in the `configs` object to protect endpoints. This will automatically run the necessary authentication middlewares and attach the authenticated user to the Hono `Context`, which can then be accessed type-safely using `TRouteContext`.
+
+```typescript
+// src/controllers/test.controller.ts
+import {
+  Authentication,
+  BaseController,
+  controller,
+  get, // Or @api, @post, etc.
+  HTTP,
+  jsonResponse,
+  IJWTTokenPayload,
+  TRouteContext, // Import TRouteContext for type safety
+} from '@venizia/ignis';
+import { z } from '@hono/zod-openapi';
+
+const SECURE_ROUTE_CONFIG = {
+  path: '/secure-data',
+  method: HTTP.Methods.GET,
+  authStrategies: [Authentication.STRATEGY_JWT],
+  responses: jsonResponse({
+      description: 'Test message content',
+      schema: z.object({ message: z.string() }),
+  }),
+} as const;
+
+@controller({ path: '/test' })
+export class TestController extends BaseController {
+  constructor() {
+    super({
+      scope: TestController.name,
+      path: '/test',
+    });
+  }
+
+  @get({ configs: SECURE_ROUTE_CONFIG })
+  secureData(c: TRouteContext<typeof SECURE_ROUTE_CONFIG>) {
+    // 'c' is fully typed here, including c.get and c.json return type
+    const user = c.get(Authentication.CURRENT_USER) as IJWTTokenPayload | undefined;
+    return c.json({ message: `Hello, ${user?.userId || 'guest'} from protected data` });
+  }
+}
+```
+
+#### 4. Accessing the Current User in Context
+
+After a route has been processed, the authenticated user's payload is available directly on the Hono `Context` object, using the `Authentication.CURRENT_USER` key.
+
+```typescript
+import { Context } from 'hono';
+import { Authentication, IJWTTokenPayload } from '@venizia/ignis';
+
+// Inside a route handler or a custom middleware
+const user = c.get(Authentication.CURRENT_USER) as IJWTTokenPayload | undefined;
+
+if (user) {
+  console.log('Authenticated user ID:', user.userId);
+  // You can also access roles, email, etc. from the user object
+} else {
+  console.log('User is not authenticated or not found in context.');
+}
+```