@venizia/ignis-docs 0.0.1-4 → 0.0.1-6

package/wiki/get-started/philosophy.md

@@ -2,28 +2,107 @@
 
 Ignis combines the structured, enterprise-grade development experience of **LoopBack 4** with the speed and simplicity of **Hono**.
 
-## The Problem
+## The Landscape
 
-When building REST APIs with Node.js/Bun, developers face a choice:
+When building REST APIs with Node.js/Bun, developers choose from three categories of frameworks, each with genuine strengths:
 
-| Aspect | Minimal Frameworks | Enterprise Frameworks | **Ignis** |
-|--------|-------------------|----------------------|-----------|
-| **Examples** | Express, Hono, Fastify | NestJS, LoopBack | **Ignis** |
-| **Performance** | ⚡ Very fast | 🐌 Slower | ⚡ Very fast (Hono) |
-| **Architecture** | ❌ No structure | ✅ Structured | ✅ Structured |
-| **Learning Curve** | ✅ Easy | ❌ Steep | ✅ Gradual |
-| **Dependency Injection** | ❌ Manual | ✅ Built-in | ✅ Built-in |
-| **Boilerplate** | ✅ Minimal | ❌ Heavy | ✅ Moderate |
-| **Best For** | Prototypes, tiny APIs | Large enterprise apps | Growing APIs, teams |
+### Framework Categories
 
-### Ignis: The Middle Ground
+| Category | Examples | Philosophy |
+|----------|----------|------------|
+| **Minimal** | Express, Hono, Fastify, Koa | Freedom, speed, flexibility |
+| **Enterprise** | NestJS, LoopBack 4, AdonisJS | Structure, patterns, conventions |
+| **Balanced** | Ignis, Ts.ED | Structure with lighter footprint |
 
-Ignis provides the architectural benefits of enterprise frameworks while maintaining Hono's speed:
+## Honest Comparison
 
-- ✅ **Enterprise patterns** (DI, layered architecture) without the bloat
-- ✅ **Hono's performance** - one of the fastest frameworks
-- ✅ **Gradual complexity** - start simple, add structure as you grow
-- ✅ **TypeScript-first** with excellent type safety
+### Performance & Runtime
+
+| Framework | Requests/sec | Startup Time | Memory | Multi-Runtime |
+|-----------|-------------|--------------|--------|---------------|
+| **Hono** | ~150k | ~10ms | ~20MB | ✅ Bun, Node, Deno, CF Workers |
+| **Fastify** | ~80k | ~50ms | ~40MB | Node only |
+| **Express** | ~15k | ~100ms | ~50MB | Node only |
+| **NestJS** | ~25k | ~500ms | ~100MB | Node (Bun experimental) |
+| **LoopBack 4** | ~20k | ~800ms | ~120MB | Node only |
+| **Ignis** | ~140k | ~30ms | ~30MB | ✅ Bun, Node |
+
+*Benchmarks are approximate and vary by use case.*
+
+### Developer Experience
+
+| Aspect | Minimal (Hono/Express) | Enterprise (NestJS/LoopBack) | Ignis |
+|--------|------------------------|------------------------------|-------|
+| **Setup Time** | 5 minutes | 30+ minutes | 10 minutes |
+| **Learning Curve** | Low | High | Medium |
+| **Boilerplate** | Minimal | Heavy | Moderate |
+| **Type Safety** | Manual | Excellent | Excellent |
+| **IDE Support** | Basic | Excellent | Good |
+| **Documentation** | Good | Excellent | Growing |
+
+### Architecture & Patterns
+
+| Pattern | Minimal | Enterprise | Ignis |
+|---------|---------|------------|-------|
+| **Dependency Injection** | ❌ Manual/3rd party | ✅ Built-in (complex) | ✅ Built-in (simple) |
+| **Layered Architecture** | ❌ DIY | ✅ Enforced | ✅ Guided |
+| **Repository Pattern** | ❌ DIY | ✅ Built-in | ✅ Built-in |
+| **Validation** | ❌ 3rd party | ✅ Built-in | ✅ Built-in (Zod) |
+| **OpenAPI/Swagger** | ❌ 3rd party | ✅ Built-in | ✅ Built-in |
+| **Authentication** | ❌ DIY | ✅ Modules available | ✅ Built-in component |
+
+### Ecosystem & Maturity
+
+| Aspect | Minimal (Hono) | Enterprise (NestJS) | Ignis |
+|--------|----------------|---------------------|-------|
+| **Community Size** | Growing fast | Very large | Small |
+| **npm Downloads** | ~500k/week | ~3M/week | New |
+| **Stack Overflow** | Limited | Extensive | Limited |
+| **Third-party Modules** | Middleware-based | Rich ecosystem | Growing |
+| **Production Battle-tested** | Yes | Yes | Emerging |
+| **Corporate Backing** | Cloudflare | Trilon | Independent |
+
+### Flexibility vs Convention
+
+| Aspect | Minimal | Enterprise | Ignis |
+|--------|---------|------------|-------|
+| **Project Structure** | Total freedom | Strict conventions | Guided conventions |
+| **ORM Choice** | Any | TypeORM/Prisma preferred | Drizzle (flexible) |
+| **Testing Approach** | Any | Jest recommended | Any |
+| **Middleware System** | Simple | Complex interceptors | Hono middleware |
+| **Customization** | Unlimited | Plugin-based | Component-based |
+
+## The Middle Ground: Where Ignis Fits
+
+### What Each Approach Excels At
+
+**Minimal Frameworks (Hono, Express, Fastify):**
+- ✅ Maximum performance
+- ✅ Complete freedom in architecture
+- ✅ Fastest prototyping
+- ✅ Smallest bundle size
+- ✅ Edge/serverless deployments
+- ⚠️ Architecture decisions left to developer
+- ⚠️ Patterns must be implemented manually
+
+**Enterprise Frameworks (NestJS, LoopBack):**
+- ✅ Battle-tested patterns
+- ✅ Comprehensive documentation
+- ✅ Large community & ecosystem
+- ✅ Excellent for large teams
+- ✅ Strong conventions prevent chaos
+- ⚠️ Higher resource consumption
+- ⚠️ Steeper learning curve
+- ⚠️ More boilerplate
+
+**Ignis (The Middle Ground):**
+- ✅ Enterprise patterns without the weight
+- ✅ Hono's performance foundation
+- ✅ Gradual complexity adoption
+- ✅ TypeScript-first with Zod validation
+- ⚠️ Smaller community (new framework)
+- ⚠️ Less documentation than mature frameworks
+- ⚠️ Fewer third-party integrations
 
 ## Inspired By The Best
 
@@ -102,17 +181,111 @@ Ignis = LoopBack patterns + Hono performance:
 - Type-safe database operations
 - Automatic validation
 
+## Choose the Right Tool
+
+### Use Hono/Fastify/Express When:
+
+| Scenario | Why It's Better |
+|----------|-----------------|
+| Building a simple webhook handler | No structure overhead needed |
+| Edge/serverless functions | Minimal cold start, tiny bundle |
+| Rapid prototyping | Get something running in minutes |
+| Microservices with 1-5 endpoints | Structure adds unnecessary complexity |
+| You want maximum control | No conventions to follow |
+| Learning web development | Simpler mental model |
+
+### Use NestJS/LoopBack When:
+
+| Scenario | Why It's Better |
+|----------|-----------------|
+| Large team (10+ developers) | Strong conventions prevent chaos |
+| Enterprise with strict standards | Mature, battle-tested, auditable |
+| Need extensive ecosystem | Many official and community modules |
+| Complex microservices architecture | Built-in support for messaging, CQRS |
+| Hiring developers easily | Large talent pool familiar with it |
+| Long-term support is critical | Corporate backing, LTS versions |
+
+### Use Ignis When:
+
+| Scenario | Why It's Better |
+|----------|-----------------|
+| Medium-sized API (10-100 endpoints) | Right balance of structure and speed |
+| Small team wanting patterns | DI without enterprise complexity |
+| Performance is critical | Hono's speed with structure |
+| Coming from LoopBack/NestJS | Familiar patterns, lighter weight |
+| Bun-first development | Native Bun support |
+| Growing project | Start simple, add complexity gradually |
+
 ## The Trade-off
 
-| You Gain | You Give Up |
-|----------|-------------|
-| Clear architecture | ~100 lines setup boilerplate |
-| Built-in DI, validation, docs | Learning curve for patterns |
-| Faster for medium/large projects | Slightly more abstraction than Hono |
-| Easier testing | Initial time investment |
-| Team scalability | Convention over total freedom |
+Every choice has trade-offs. Here's an honest look:
 
-**Bottom line:** If you're building more than a simple API, the structure pays off in maintainability and productivity.
+### What You Gain with Ignis
+
+| Benefit | Compared To |
+|---------|-------------|
+| ~5x faster than NestJS | Enterprise frameworks |
+| Built-in DI, validation, OpenAPI | Minimal frameworks |
+| Structured codebase | DIY architecture |
+| Easier testing with DI | Manual mocking |
+| Team-friendly patterns | Individual coding styles |
+
+### What You Give Up with Ignis
+
+| Trade-off | Compared To |
+|-----------|-------------|
+| ~10% slower than raw Hono | Minimal frameworks |
+| Smaller community | NestJS/Express |
+| Less documentation | Mature frameworks |
+| Learning curve for patterns | No-structure approach |
+| Convention requirements | Total freedom |
+
+### Honest Assessment
+
+| Aspect | Ignis Reality |
+|--------|---------------|
+| **Maturity** | New framework, evolving API |
+| **Community** | Small but growing |
+| **Documentation** | Good but not comprehensive |
+| **Production Use** | Early adopters only |
+| **Breaking Changes** | Possible before v1.0 |
+| **Support** | Community-driven |
+
+**Bottom line:** Ignis is ideal for developers who want enterprise patterns without enterprise overhead. If you need battle-tested stability and extensive community support, consider NestJS. If you need maximum simplicity, stick with Hono.
+
+## Migration Paths
+
+### From Hono to Ignis
+
+If your Hono project grows complex:
+
+```
+1. Add Ignis as dependency
+2. Wrap existing Hono app with Ignis Application
+3. Gradually introduce DI for new features
+4. Migrate routes to controllers over time
+```
+
+### From NestJS to Ignis
+
+If you want better performance:
+
+```
+1. Controllers → Ignis Controllers (similar decorators)
+2. Services → Ignis Services (same pattern)
+3. Repositories → Ignis Repositories (Drizzle instead of TypeORM)
+4. Modules → Ignis Components (simpler structure)
+```
+
+### From Ignis to NestJS
+
+If you outgrow Ignis:
+
+```
+1. Patterns are similar - migration is straightforward
+2. Main changes: ORM, module system, interceptors
+3. DI concepts transfer directly
+```
 
 ## Next Steps
 

package/wiki/public/logo.svg

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="utf-8"?><svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" viewBox="0 0 92.27 122.88" style="enable-background:new 0 0 92.27 122.88" xml:space="preserve"><style type="text/css">.st0{fill-rule:evenodd;clip-rule:evenodd;fill:#EC6F59;} .st1{fill-rule:evenodd;clip-rule:evenodd;fill:#FAD15C;}</style><g><path class="st0" d="M18.61,54.89C15.7,28.8,30.94,10.45,59.52,0C42.02,22.71,74.44,47.31,76.23,70.89 c4.19-7.15,6.57-16.69,7.04-29.45c21.43,33.62,3.66,88.57-43.5,80.67c-4.33-0.72-8.5-2.09-12.3-4.13C10.27,108.8,0,88.79,0,69.68 C0,57.5,5.21,46.63,11.95,37.99C12.85,46.45,14.77,52.76,18.61,54.89L18.61,54.89z"/><path class="st1" d="M33.87,92.58c-4.86-12.55-4.19-32.82,9.42-39.93c0.1,23.3,23.05,26.27,18.8,51.14 c3.92-4.44,5.9-11.54,6.25-17.15c6.22,14.24,1.34,25.63-7.53,31.43c-26.97,17.64-50.19-18.12-34.75-37.72 C26.53,84.73,31.89,91.49,33.87,92.58L33.87,92.58z"/></g></svg>

package/wiki/references/base/application.md

@@ -37,11 +37,11 @@ Extends `AbstractApplication` with concrete lifecycle implementations and resour
 
 | Method | DI Binding Key Convention |
 | :--- | :--- |
-| `component(MyComponent)` | `components.MyComponent` |
-| `controller(MyController)` | `controllers.MyController` |
-| `service(MyService)` | `services.MyService` |
-| `repository(MyRepository)`| `repositories.MyRepository` |
-| `dataSource(MyDataSource)`| `datasources.MyDataSource` |
+| `component(MyComponent, opts?)` | `components.MyComponent` (default) or custom key via `opts.binding` |
+| `controller(MyController, opts?)` | `controllers.MyController` (default) or custom key via `opts.binding` |
+| `service(MyService, opts?)` | `services.MyService` (default) or custom key via `opts.binding` |
+| `repository(MyRepository, opts?)`| `repositories.MyRepository` (default) or custom key via `opts.binding` |
+| `dataSource(MyDataSource, opts?)`| `datasources.MyDataSource` (default) or custom key via `opts.binding` |
 
 ### `initialize()` Method Flow
 

package/wiki/references/base/controllers.md

@@ -287,7 +287,9 @@ The `ControllerFactory` provides a static method `defineCrudController` to quick
 
 ### `static defineCrudController<EntitySchema>(opts: ICrudControllerOptions<EntitySchema>)`
 
-This factory method returns a `BaseController` class that is already set up with the following standard CRUD endpoints:
+This factory method returns a `BaseController` class that is already set up with the following standard CRUD endpoints.
+
+**Note:** The returned class is dynamically named using `controller.name` from the options. This ensures that when registered with `app.controller()`, the class has a proper name for binding keys and debugging (e.g., `ConfigurationController` instead of an anonymous class).
 
 | Name | Method | Path | Description |
 | :--- | :--- | :--- | :--- |

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

@@ -3,9 +3,10 @@
 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`
+- `packages/inversion/src/container.ts` (base Container and Binding classes)
+- `packages/helpers/src/helpers/inversion/container.ts` (extended Container with ApplicationLogger)
+- `packages/core/src/base/metadata/injectors.ts` (@inject, @injectable decorators)
+- `packages/helpers/src/helpers/inversion/registry.ts` (MetadataRegistry)
 
 ## Quick Reference
 
@@ -20,7 +21,7 @@ Technical reference for the DI system in Ignis - managing resource lifecycles an
 
 Heart of the DI system - registry managing all application resources.
 
-**File:** `packages/core/src/helpers/inversion/container.ts`
+**File:** `packages/inversion/src/container.ts`
 
 ### Key Methods
 
@@ -35,7 +36,7 @@ Heart of the DI system - registry managing all application resources.
 
 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`
+-   **File:** `packages/inversion/src/container.ts`
 
 ### Configuration Methods
 

package/wiki/references/base/models.md

@@ -79,7 +79,7 @@ Enrichers are helper functions located in `packages/core/src/base/models/enriche
 | 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. |
+| **`generateTzColumnDefs`** | Adds `createdAt`, `modifiedAt`, and `deletedAt` 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. |
@@ -102,3 +102,321 @@ export const myTable = pgTable('MyTable', {
   name: text('name').notNull(),
 });
 ```
+
+---
+
+## Detailed Enricher Reference
+
+### `generateTzColumnDefs`
+
+Adds timestamp columns for tracking entity creation, modification, and soft deletion.
+
+**File:** `packages/core/src/base/models/enrichers/tz.enricher.ts`
+
+#### Signature
+
+```typescript
+generateTzColumnDefs(opts?: TTzEnricherOptions): TTzEnricherResult
+```
+
+#### Options (`TTzEnricherOptions`)
+
+```typescript
+type TTzEnricherOptions = {
+  created?: { columnName: string; withTimezone: boolean };
+  modified?: { enable: boolean; columnName: string; withTimezone: boolean };
+  deleted?: { enable: boolean; columnName: string; withTimezone: boolean };
+};
+```
+
+**Default values:**
+- `created`: `{ columnName: 'created_at', withTimezone: true }`
+- `modified`: `{ enable: true, columnName: 'modified_at', withTimezone: true }`
+- `deleted`: `{ enable: false }` (disabled by default)
+
+#### Generated Columns
+
+| Column | Type | Constraints | Default | Description |
+|--------|------|-------------|---------|-------------|
+| `createdAt` | `timestamp` | `NOT NULL` | `now()` | When the record was created (always included) |
+| `modifiedAt` | `timestamp` | `NOT NULL` | `now()` | When the record was last modified (optional, enabled by default) |
+| `deletedAt` | `timestamp` | nullable | `null` | When the record was soft-deleted (optional, **disabled by default**) |
+
+#### Usage Examples
+
+**Basic usage (default columns):**
+
+```typescript
+import { pgTable, text } from 'drizzle-orm/pg-core';
+import { generateTzColumnDefs } from '@venizia/ignis';
+
+export const myTable = pgTable('MyTable', {
+  ...generateTzColumnDefs(),
+  name: text('name').notNull(),
+});
+
+// Generates: createdAt, modifiedAt (deletedAt is disabled by default)
+```
+
+**Enable soft delete:**
+
+```typescript
+export const myTable = pgTable('MyTable', {
+  ...generateTzColumnDefs({
+    deleted: { enable: true, columnName: 'deleted_at', withTimezone: true },
+  }),
+  name: text('name').notNull(),
+});
+
+// Generates: createdAt, modifiedAt, deletedAt
+```
+
+**Custom column names:**
+
+```typescript
+export const myTable = pgTable('MyTable', {
+  ...generateTzColumnDefs({
+    created: { columnName: 'created_date', withTimezone: true },
+    modified: { enable: true, columnName: 'updated_date', withTimezone: true },
+    deleted: { enable: true, columnName: 'removed_date', withTimezone: true },
+  }),
+  name: text('name').notNull(),
+});
+```
+
+**Without timezone:**
+
+```typescript
+export const myTable = pgTable('MyTable', {
+  ...generateTzColumnDefs({
+    created: { columnName: 'created_at', withTimezone: false },
+    modified: { enable: true, columnName: 'modified_at', withTimezone: false },
+    deleted: { enable: true, columnName: 'deleted_at', withTimezone: false },
+  }),
+  name: text('name').notNull(),
+});
+```
+
+
+
+**Minimal setup (only createdAt):**
+
+```typescript
+export const myTable = pgTable('MyTable', {
+  ...generateTzColumnDefs({
+    modified: { enable: false },
+    deleted: { enable: false },
+  }),
+  name: text('name').notNull(),
+});
+
+// Generates: createdAt only
+```
+
+#### Soft Delete Pattern
+
+The `deletedAt` column enables the soft delete pattern, where records are marked as deleted rather than physically removed from the database.
+
+**Example soft delete query:**
+
+```typescript
+import { eq, isNull } from 'drizzle-orm';
+
+// Soft delete: set deletedAt timestamp
+await db.update(myTable)
+  .set({ deletedAt: new Date() })
+  .where(eq(myTable.id, id));
+
+// Query only active (non-deleted) records
+const activeRecords = await db.select()
+  .from(myTable)
+  .where(isNull(myTable.deletedAt));
+
+// Query deleted records
+const deletedRecords = await db.select()
+  .from(myTable)
+  .where(isNotNull(myTable.deletedAt));
+
+// Restore a soft-deleted record
+await db.update(myTable)
+  .set({ deletedAt: null })
+  .where(eq(myTable.id, id));
+```
+
+#### Type Inference
+
+The enricher provides proper TypeScript type inference:
+
+```typescript
+type TTzEnricherResult<ColumnDefinitions extends TColumnDefinitions = TColumnDefinitions> = {
+  createdAt: PgTimestampBuilderInitial<string> & NotNull & HasDefault;
+  modifiedAt?: PgTimestampBuilderInitial<string> & NotNull & HasDefault;
+  deletedAt?: PgTimestampBuilderInitial<string>;
+};
+```
+
+---
+
+## Schema Utilities
+
+### `snakeToCamel`
+
+Converts a Zod schema from snake_case to camelCase, transforming both the schema shape and runtime data.
+
+**File:** `packages/core/src/base/models/common/types.ts`
+
+#### Signature
+
+```typescript
+snakeToCamel<T extends z.ZodRawShape>(shape: T): z.ZodEffects<...>
+```
+
+#### Purpose
+
+This utility is useful when working with databases that use snake_case column names but you want to work with camelCase in your TypeScript code. It creates a Zod schema that:
+
+1. Accepts snake_case input (validates against original schema)
+2. Transforms the data to camelCase at runtime
+3. Validates the transformed data against a camelCase schema
+
+#### Usage Example
+
+```typescript
+import { z } from 'zod';
+import { snakeToCamel } from '@venizia/ignis';
+
+// Define schema with snake_case fields
+const userSnakeSchema = {
+  user_id: z.number(),
+  first_name: z.string(),
+  last_name: z.string(),
+  created_at: z.date(),
+  is_active: z.boolean(),
+};
+
+// Convert to camelCase schema
+const userCamelSchema = snakeToCamel(userSnakeSchema);
+
+// Input data from database (snake_case)
+const dbData = {
+  user_id: 123,
+  first_name: 'John',
+  last_name: 'Doe',
+  created_at: new Date(),
+  is_active: true,
+};
+
+// Parse and transform to camelCase
+const result = userCamelSchema.parse(dbData);
+
+// Result is automatically camelCase:
+console.log(result);
+// {
+//   userId: 123,
+//   firstName: 'John',
+//   lastName: 'Doe',
+//   createdAt: Date,
+//   isActive: true
+// }
+```
+
+#### Real-world Example
+
+**Use case:** API endpoint that accepts snake_case but works with camelCase internally
+
+```typescript
+import { BaseController, controller, snakeToCamel } from '@venizia/ignis';
+import { z } from '@hono/zod-openapi';
+
+const createUserSchema = snakeToCamel({
+  first_name: z.string().min(1),
+  last_name: z.string().min(1),
+  email_address: z.string().email(),
+  phone_number: z.string().optional(),
+});
+
+@controller({ path: '/users' })
+export class UserController extends BaseController {
+  override binding() {
+    this.bindRoute({
+      configs: {
+        path: '/',
+        method: 'post',
+        request: {
+          body: {
+            content: {
+              'application/json': { schema: createUserSchema },
+            },
+          },
+        },
+      },
+    }).to({
+      handler: async (ctx) => {
+        // Request body is automatically camelCase
+        const data = ctx.req.valid('json');
+        
+        // data = {
+        //   firstName: string,
+        //   lastName: string,
+        //   emailAddress: string,
+        //   phoneNumber?: string
+        // }
+        
+        // Work with camelCase data
+        console.log(data.firstName);  // ✅ TypeScript knows this exists
+        console.log(data.first_name);  // ❌ TypeScript error
+        
+        return ctx.json({ success: true });
+      },
+    });
+  }
+}
+```
+
+#### Type Transformation
+
+The utility includes sophisticated TypeScript type transformation:
+
+```typescript
+type TSnakeToCamelCase<S extends string> = 
+  S extends `${infer T}_${infer U}`
+    ? `${T}${Capitalize<TSnakeToCamelCase<U>>}`
+    : S;
+
+type TCamelCaseKeys<T extends z.ZodRawShape> = {
+  [K in keyof T as K extends string ? TSnakeToCamelCase<K> : K]: 
+    T[K] extends z.ZodType<infer U> ? z.ZodType<U> : T[K];
+};
+```
+
+This ensures full type safety: TypeScript will know that `first_name` becomes `firstName`, `created_at` becomes `createdAt`, etc.
+
+#### Validation
+
+The schema validates twice for safety:
+
+1. **First validation:** Checks that input matches snake_case schema
+2. **Transformation:** Converts keys from snake_case to camelCase
+3. **Second validation:** Validates transformed data against camelCase schema
+
+```typescript
+// If validation fails at any step, you get clear error messages
+const invalidData = {
+  user_id: 'not-a-number',  // ❌ Fails first validation
+  first_name: 'John',
+  last_name: 'Doe',
+};
+
+try {
+  userCamelSchema.parse(invalidData);
+} catch (error) {
+  // ZodError with clear message about user_id expecting number
+}
+```
+
+#### Notes
+
+- Built on top of `keysToCamel()` and `toCamel()` utilities from `@venizia/ignis-helpers`
+- Recursively handles nested objects
+- Preserves array structures
+- Works seamlessly with Zod's other features (refinements, transforms, etc.)

package/wiki/references/components/index.md

@@ -8,8 +8,10 @@ Reusable, pluggable modules that encapsulate specific features in Ignis applicat
 |-----------|---------|--------------|
 | [Authentication](./authentication.md) | JWT-based auth | Token generation, protected routes, user payload |
 | [Health Check](./health-check.md) | Monitoring endpoint | `/health` endpoint, ping/pong functionality |
-| [Swagger](./swagger.md) | API documentation | OpenAPI generation, Swagger UI, Scalar UI |
+| [Request Tracker](./request-tracker.md) | Request logging | Request ID generation, timing, structured logging |
 | [Socket.IO](./socket-io.md) | Real-time communication | WebSocket support, Redis adapter, event-based |
+| [Static Asset](./static-asset.md) | File management | Upload/download files, MinIO & local filesystem support |
+| [Swagger](./swagger.md) | API documentation | OpenAPI generation, Swagger UI, Scalar UI |
 
 ## Creating a Component