@venizia/ignis-docs 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ignis-docs",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Documentation and MCP Server for Ignis Framework",
   "keywords": [
     "ignis",

package/wiki/changelogs/index.md

@@ -12,6 +12,7 @@ This section tracks the history of significant changes, refactors, and updates t
 | Feature | Description | Priority |
 |---------|-------------|----------|
 | [Transaction Support](./planned-transaction-support) | Loopback 4-style explicit transaction objects with isolation levels | Future |
+| [Schema Migrator](./planned-schema-migrator) | LoopBack 4-style auto schema migration without Drizzle Kit | High |
 
 ## Recent Changes
 

package/wiki/changelogs/planned-schema-migrator.md

@@ -0,0 +1,561 @@
+---
+title: Planned - Schema Migrator (Auto-Update)
+description: Implementation plan for LoopBack 4-style auto schema migration without Drizzle Kit
+---
+
+# Planned: Schema Migrator (Auto-Update)
+
+**Status:** Planned (Not Yet Implemented)
+**Priority:** High
+
+## Goal
+
+Implement LoopBack 4-style automatic schema migration that reads model definitions from `@model` decorated classes and syncs them to the database. No external CLI tools (like Drizzle Kit) required.
+
+Key principle: **Never drop tables or lose data** - only apply incremental changes (ADD/ALTER/DROP columns).
+
+## Target API
+
+```typescript
+// In application boot
+const migrator = dataSource.getMigrator();
+
+// Auto-update: safe, only applies differences
+await migrator.autoupdate();
+
+// Or with options
+await migrator.autoupdate({
+  models: [User, Role], // Specific models only (optional)
+  dryRun: true,         // Preview SQL without executing
+});
+
+// Fresh start (destructive - use with caution)
+await migrator.automigrate(); // Drops and recreates all tables
+```
+
+### Migration Behaviors
+
+| Method | Behavior | Data Loss |
+|--------|----------|-----------|
+| `autoupdate()` | Compares DB ↔ Model, applies ALTER statements | **No** |
+| `automigrate()` | Drops and recreates tables | **Yes** |
+
+---
+
+## Implementation Steps
+
+### Step 1: Define Migrator Types
+
+**File:** `packages/core/src/base/datasources/types.ts`
+
+```typescript
+/** Column information from database introspection */
+export interface IColumnInfo {
+  column_name: string;
+  data_type: string;
+  is_nullable: 'YES' | 'NO';
+  column_default: string | null;
+  character_maximum_length: number | null;
+}
+
+/** Constraint information from database */
+export interface IConstraintInfo {
+  constraint_name: string;
+  constraint_type: 'PRIMARY KEY' | 'FOREIGN KEY' | 'UNIQUE' | 'CHECK';
+  column_name: string;
+  foreign_table_name?: string;
+  foreign_column_name?: string;
+}
+
+/** Index information from database */
+export interface IIndexInfo {
+  index_name: string;
+  column_name: string;
+  is_unique: boolean;
+}
+
+/** Options for autoupdate */
+export interface IAutoupdateOptions {
+  /** Only migrate specific models (default: all registered models) */
+  models?: Array<typeof BaseEntity>;
+  /** Preview SQL without executing (default: false) */
+  dryRun?: boolean;
+  /** Log generated SQL statements (default: true) */
+  verbose?: boolean;
+}
+
+/** Options for automigrate */
+export interface IAutomigrateOptions extends IAutoupdateOptions {
+  /** Skip confirmation for destructive operation (default: false) */
+  force?: boolean;
+}
+
+/** Result of migration operation */
+export interface IMigrationResult {
+  /** Tables created */
+  created: string[];
+  /** Tables altered */
+  altered: string[];
+  /** SQL statements executed (or would be executed if dryRun) */
+  statements: string[];
+  /** Errors encountered */
+  errors: Array<{ table: string; error: string }>;
+}
+```
+
+### Step 2: Create Schema Introspector
+
+**File:** `packages/core/src/base/datasources/introspector.ts`
+
+```typescript
+import { sql } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+
+/**
+ * Introspects PostgreSQL database schema using information_schema
+ */
+export class SchemaIntrospector {
+  constructor(private db: NodePgDatabase) {}
+
+  /** Check if table exists */
+  async tableExists(tableName: string): Promise<boolean>;
+
+  /** Get all columns for a table */
+  async getColumns(tableName: string): Promise<Map<string, IColumnInfo>>;
+
+  /** Get all constraints for a table */
+  async getConstraints(tableName: string): Promise<IConstraintInfo[]>;
+
+  /** Get all indexes for a table */
+  async getIndexes(tableName: string): Promise<IIndexInfo[]>;
+
+  /** Get all table names in public schema */
+  async getAllTables(): Promise<string[]>;
+}
+```
+
+**Key Queries:**
+
+```sql
+-- Get columns
+SELECT column_name, data_type, is_nullable, column_default, character_maximum_length
+FROM information_schema.columns
+WHERE table_schema = 'public' AND table_name = $1;
+
+-- Get constraints
+SELECT tc.constraint_name, tc.constraint_type, kcu.column_name,
+       ccu.table_name AS foreign_table_name, ccu.column_name AS foreign_column_name
+FROM information_schema.table_constraints tc
+JOIN information_schema.key_column_usage kcu ON tc.constraint_name = kcu.constraint_name
+LEFT JOIN information_schema.constraint_column_usage ccu ON tc.constraint_name = ccu.constraint_name
+WHERE tc.table_schema = 'public' AND tc.table_name = $1;
+
+-- Get indexes
+SELECT i.relname AS index_name, a.attname AS column_name, ix.indisunique AS is_unique
+FROM pg_class t
+JOIN pg_index ix ON t.oid = ix.indrelid
+JOIN pg_class i ON i.oid = ix.indexrelid
+JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(ix.indkey)
+WHERE t.relname = $1;
+```
+
+### Step 3: Create Schema Differ
+
+**File:** `packages/core/src/base/datasources/differ.ts`
+
+```typescript
+import { getTableConfig, PgTable, PgColumn } from 'drizzle-orm/pg-core';
+
+/** Types of schema changes */
+export type TSchemaChange =
+  | { type: 'CREATE_TABLE'; table: string; sql: string }
+  | { type: 'ADD_COLUMN'; table: string; column: string; sql: string }
+  | { type: 'DROP_COLUMN'; table: string; column: string; sql: string }
+  | { type: 'ALTER_COLUMN_TYPE'; table: string; column: string; sql: string }
+  | { type: 'ALTER_COLUMN_NULL'; table: string; column: string; sql: string }
+  | { type: 'ADD_CONSTRAINT'; table: string; constraint: string; sql: string }
+  | { type: 'DROP_CONSTRAINT'; table: string; constraint: string; sql: string }
+  | { type: 'ADD_INDEX'; table: string; index: string; sql: string }
+  | { type: 'DROP_INDEX'; table: string; index: string; sql: string };
+
+/**
+ * Compares model schema with database schema and generates changes
+ */
+export class SchemaDiffer {
+  constructor(private introspector: SchemaIntrospector) {}
+
+  /** Compare a single model with database and return changes */
+  async diffTable(schema: PgTable): Promise<TSchemaChange[]>;
+
+  /** Compare all models with database */
+  async diffAll(schemas: PgTable[]): Promise<TSchemaChange[]>;
+}
+```
+
+**Diff Logic:**
+
+```typescript
+async diffTable(schema: PgTable): Promise<TSchemaChange[]> {
+  const config = getTableConfig(schema);
+  const tableName = config.name;
+  const changes: TSchemaChange[] = [];
+
+  const tableExists = await this.introspector.tableExists(tableName);
+
+  if (!tableExists) {
+    // Generate CREATE TABLE
+    changes.push({
+      type: 'CREATE_TABLE',
+      table: tableName,
+      sql: this.generateCreateTable(config),
+    });
+    return changes;
+  }
+
+  // Table exists - compare columns
+  const dbColumns = await this.introspector.getColumns(tableName);
+  const modelColumns = new Map(Object.entries(config.columns));
+
+  // Find columns to ADD
+  for (const [colName, colDef] of modelColumns) {
+    if (!dbColumns.has(colName)) {
+      changes.push({
+        type: 'ADD_COLUMN',
+        table: tableName,
+        column: colName,
+        sql: `ALTER TABLE "${tableName}" ADD COLUMN ${this.columnToSQL(colName, colDef)}`,
+      });
+    }
+  }
+
+  // Find columns to DROP
+  for (const [colName] of dbColumns) {
+    if (!modelColumns.has(colName)) {
+      changes.push({
+        type: 'DROP_COLUMN',
+        table: tableName,
+        column: colName,
+        sql: `ALTER TABLE "${tableName}" DROP COLUMN "${colName}"`,
+      });
+    }
+  }
+
+  // Find columns to ALTER
+  for (const [colName, colDef] of modelColumns) {
+    const dbCol = dbColumns.get(colName);
+    if (dbCol) {
+      changes.push(...this.diffColumn(tableName, colName, colDef, dbCol));
+    }
+  }
+
+  // Diff constraints and indexes...
+  return changes;
+}
+```
+
+### Step 4: Create Type Mapper
+
+**File:** `packages/core/src/base/datasources/type-mapper.ts`
+
+```typescript
+import { PgColumn } from 'drizzle-orm/pg-core';
+
+/**
+ * Maps between Drizzle column types and PostgreSQL types
+ */
+export class TypeMapper {
+  /** Convert Drizzle column to PostgreSQL type string */
+  static drizzleToPostgres(column: PgColumn): string {
+    const type = column.dataType;
+
+    switch (type) {
+      case 'string': return column.length ? `varchar(${column.length})` : 'text';
+      case 'number': return 'integer';
+      case 'bigint': return 'bigint';
+      case 'boolean': return 'boolean';
+      case 'date': return 'timestamp';
+      case 'json': return 'jsonb';
+      case 'uuid': return 'uuid';
+      case 'custom': return column.sqlName; // For custom types
+      default: return 'text';
+    }
+  }
+
+  /** Check if two types are compatible (for ALTER TYPE) */
+  static isCompatible(pgType: string, drizzleType: string): boolean;
+
+  /** Generate USING clause for type conversion if needed */
+  static getTypeConversion(from: string, to: string): string | null;
+}
+```
+
+### Step 5: Create Schema Migrator
+
+**File:** `packages/core/src/base/datasources/migrator.ts`
+
+```typescript
+import { MetadataRegistry } from '@/helpers/inversion';
+import { SchemaIntrospector } from './introspector';
+import { SchemaDiffer } from './differ';
+
+/**
+ * LoopBack 4-style schema migrator
+ * Syncs model definitions to database without external CLI tools
+ */
+export class SchemaMigrator {
+  private introspector: SchemaIntrospector;
+  private differ: SchemaDiffer;
+
+  constructor(private db: NodePgDatabase) {
+    this.introspector = new SchemaIntrospector(db);
+    this.differ = new SchemaDiffer(this.introspector);
+  }
+
+  /**
+   * Auto-update schema - safe, incremental changes only
+   * Like LoopBack 4's datasource.autoupdate()
+   */
+  async autoupdate(opts?: IAutoupdateOptions): Promise<IMigrationResult> {
+    const schemas = this.getSchemas(opts?.models);
+    const changes = await this.differ.diffAll(schemas);
+
+    if (opts?.dryRun) {
+      return this.buildResult(changes, { executed: false });
+    }
+
+    return this.executeChanges(changes, opts);
+  }
+
+  /**
+   * Auto-migrate schema - destructive, drops and recreates
+   * Like LoopBack 4's datasource.automigrate()
+   */
+  async automigrate(opts?: IAutomigrateOptions): Promise<IMigrationResult> {
+    if (!opts?.force) {
+      throw getError({
+        message: '[automigrate] Destructive operation requires force: true',
+      });
+    }
+
+    const schemas = this.getSchemas(opts?.models);
+
+    // Drop tables in reverse order (for FK constraints)
+    for (const schema of [...schemas].reverse()) {
+      const tableName = getTableConfig(schema).name;
+      await this.db.execute(sql.raw(`DROP TABLE IF EXISTS "${tableName}" CASCADE`));
+    }
+
+    // Create all tables fresh
+    const changes = schemas.map(schema => ({
+      type: 'CREATE_TABLE' as const,
+      table: getTableConfig(schema).name,
+      sql: this.generateCreateTable(schema),
+    }));
+
+    return this.executeChanges(changes, opts);
+  }
+
+  /** Get schemas from registry or specific models */
+  private getSchemas(models?: Array<typeof BaseEntity>): PgTable[] {
+    if (models) {
+      return models.map(m => m.schema);
+    }
+
+    const registry = MetadataRegistry.getInstance();
+    const allModels = registry.getAllModels();
+    return [...allModels.values()].map(entry => entry.schema);
+  }
+
+  /** Execute schema changes */
+  private async executeChanges(
+    changes: TSchemaChange[],
+    opts?: { verbose?: boolean }
+  ): Promise<IMigrationResult>;
+}
+```
+
+### Step 6: Integrate with DataSource
+
+**File:** `packages/core/src/base/datasources/base.ts`
+
+```typescript
+export abstract class BaseDataSource<...> {
+  private _migrator?: SchemaMigrator;
+
+  /**
+   * Get schema migrator instance
+   * Like LoopBack 4's datasource property
+   */
+  getMigrator(): SchemaMigrator {
+    if (!this._migrator) {
+      this._migrator = new SchemaMigrator(this.connector);
+    }
+    return this._migrator;
+  }
+
+  /**
+   * Convenience method: auto-update schema
+   */
+  async autoupdate(opts?: IAutoupdateOptions): Promise<IMigrationResult> {
+    return this.getMigrator().autoupdate(opts);
+  }
+
+  /**
+   * Convenience method: auto-migrate schema (destructive)
+   */
+  async automigrate(opts?: IAutomigrateOptions): Promise<IMigrationResult> {
+    return this.getMigrator().automigrate(opts);
+  }
+}
+```
+
+---
+
+## Files to Create
+
+| File | Purpose |
+|------|---------|
+| `packages/core/src/base/datasources/migrator.ts` | Main SchemaMigrator class |
+| `packages/core/src/base/datasources/introspector.ts` | Database schema introspection |
+| `packages/core/src/base/datasources/differ.ts` | Schema comparison logic |
+| `packages/core/src/base/datasources/type-mapper.ts` | Drizzle ↔ PostgreSQL type mapping |
+
+## Files to Modify
+
+| File | Changes |
+|------|---------|
+| `packages/core/src/base/datasources/types.ts` | Add migration types and interfaces |
+| `packages/core/src/base/datasources/base.ts` | Add `getMigrator()`, `autoupdate()`, `automigrate()` |
+| `packages/core/src/base/datasources/index.ts` | Export new classes |
+
+---
+
+## Drizzle to PostgreSQL Type Mapping
+
+| Drizzle | PostgreSQL | Notes |
+|---------|------------|-------|
+| `text()` | `text` | Variable-length string |
+| `varchar({ length })` | `varchar(n)` | Fixed max length |
+| `integer()` | `integer` | 32-bit signed |
+| `bigint()` | `bigint` | 64-bit signed |
+| `serial()` | `serial` | Auto-increment |
+| `boolean()` | `boolean` | true/false |
+| `timestamp()` | `timestamp` | Date and time |
+| `date()` | `date` | Date only |
+| `json()` | `json` | JSON storage |
+| `jsonb()` | `jsonb` | Binary JSON (indexed) |
+| `uuid()` | `uuid` | UUID type |
+| `numeric({ precision, scale })` | `numeric(p,s)` | Exact decimal |
+| `real()` | `real` | 32-bit float |
+| `doublePrecision()` | `double precision` | 64-bit float |
+
+---
+
+## Change Detection Matrix
+
+| Change Type | Detection Method | SQL Generated |
+|-------------|------------------|---------------|
+| New table | Table not in DB | `CREATE TABLE` |
+| New column | Column not in DB | `ALTER TABLE ADD COLUMN` |
+| Removed column | Column not in model | `ALTER TABLE DROP COLUMN` |
+| Type change | Compare data_type | `ALTER TABLE ALTER COLUMN TYPE` |
+| Nullability | Compare is_nullable | `SET NOT NULL` / `DROP NOT NULL` |
+| Default change | Compare column_default | `SET DEFAULT` / `DROP DEFAULT` |
+| New FK | Constraint not in DB | `ADD CONSTRAINT ... FOREIGN KEY` |
+| Removed FK | Constraint not in model | `DROP CONSTRAINT` |
+| New index | Index not in DB | `CREATE INDEX` |
+| Removed index | Index not in model | `DROP INDEX` |
+
+---
+
+## Usage Examples
+
+### Basic Auto-Update (Recommended)
+
+```typescript
+// Boot application
+const app = new MyApplication();
+await app.boot();
+
+// Auto-update all models
+const dataSource = app.getSync<PostgresDataSource>('datasources.PostgresDataSource');
+const result = await dataSource.autoupdate();
+
+console.log('Created tables:', result.created);
+console.log('Altered tables:', result.altered);
+console.log('SQL executed:', result.statements);
+```
+
+### Dry Run (Preview Changes)
+
+```typescript
+const result = await dataSource.autoupdate({ dryRun: true });
+
+console.log('Would execute:');
+for (const sql of result.statements) {
+  console.log(sql);
+}
+```
+
+### Migrate Specific Models
+
+```typescript
+import { User, Role } from './models';
+
+await dataSource.autoupdate({
+  models: [User, Role],
+});
+```
+
+### Fresh Database (Development Only)
+
+```typescript
+if (process.env.NODE_ENV === 'development') {
+  await dataSource.automigrate({ force: true });
+}
+```
+
+---
+
+## Safety Considerations
+
+### autoupdate() Guarantees
+
+| Guarantee | Description |
+|-----------|-------------|
+| No table drops | Never drops tables, even if removed from models |
+| No data loss | Column drops are explicit (column must be removed from model) |
+| Transactional | Each ALTER runs in its own transaction |
+| Idempotent | Safe to run multiple times |
+
+### Dangerous Operations (Require Confirmation)
+
+| Operation | Risk | Mitigation |
+|-----------|------|------------|
+| `DROP COLUMN` | Data loss | Logged with warning |
+| `ALTER TYPE` | May fail if incompatible | Checks compatibility first |
+| `automigrate()` | Drops all tables | Requires `force: true` |
+
+---
+
+## Future Enhancements
+
+1. **Migration History Table** - Track applied migrations in `_ignis_migrations`
+2. **Rollback Support** - Generate reverse migrations
+3. **Data Migrations** - LoopBack 4-style numbered data seed files
+4. **Multi-Schema Support** - Support for PostgreSQL schemas beyond `public`
+5. **MySQL/SQLite Support** - Extend beyond PostgreSQL
+
+---
+
+## Comparison with Alternatives
+
+| Feature | Ignis Migrator | Drizzle Kit | LoopBack 4 |
+|---------|----------------|-------------|------------|
+| CLI required | No | Yes | No |
+| Auto-discovery | Yes (from @model) | No (manual schema file) | Yes |
+| Incremental updates | Yes | Yes | Yes |
+| Dry run | Yes | Yes | No |
+| Type safety | Full | Full | Partial |
+| Random file names | No | Yes | No |
+| Bidirectional | Planned | No | No |

package/wiki/get-started/best-practices/code-style-standards.md

@@ -15,7 +15,7 @@ This package provides:
 - **Prettier settings** - Consistent formatting across all Ignis projects
 - **TypeScript configs** - Shared base and common configurations
 
-## Prettier Configuration
+### Prettier Configuration
 
 Automatic code formatting eliminates style debates.
 
@@ -50,9 +50,7 @@ bun run prettier:cli      # Check formatting
 bun run prettier:fix      # Auto-fix
 ```
 
-**IDE Integration:** Configure your editor to format on save.
-
-## ESLint Configuration
+### ESLint Configuration
 
 Prevents common errors and enforces best practices.
 
@@ -88,9 +86,7 @@ bun run eslint --fix     # Auto-fix issues
 bun run lint:fix         # Run both ESLint + Prettier
 ```
 
-**Pre-commit Hook:** Add ESLint to your pre-commit hooks to catch issues before committing.
-
-## TypeScript Configuration
+### TypeScript Configuration
 
 Use the centralized TypeScript configs:
 
@@ -121,6 +117,358 @@ Use the centralized TypeScript configs:
 
 See [`@venizia/dev-configs` documentation](../../references/src-details/dev-configs.md) for full details.
 
+## Naming Conventions
+
+### Class Names
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Components | `[Feature]Component` | `HealthCheckComponent`, `AuthComponent` |
+| Controllers | `[Feature]Controller` | `UserController`, `AuthController` |
+| Services | `[Feature]Service` | `JWTTokenService`, `PaymentService` |
+| Repositories | `[Feature]Repository` | `UserRepository`, `OrderRepository` |
+| Strategies | `[Feature]Strategy` | `JWTAuthenticationStrategy` |
+| Factories | `[Feature]Factory` | `UIProviderFactory` |
+
+### File Names
+
+Both styles are acceptable: `[type].ts` or `[name].[type].ts`
+
+| Type | Single File | Multiple Files |
+|------|-------------|----------------|
+| Components | `component.ts` | `auth.component.ts` |
+| Controllers | `controller.ts` | `user.controller.ts` |
+| Services | `service.ts` | `jwt-token.service.ts` |
+| Repositories | `repository.ts` | `user.repository.ts` |
+| Types/Interfaces | `types.ts` | `user.types.ts` |
+| Constants | `constants.ts` | `keys.ts`, `rest-paths.ts` |
+| Schemas | `schema.ts` | `sign-in.schema.ts` |
+
+**Guidelines:**
+- Use `[type].ts` when there's only one file of that type in the folder
+- Use `[name].[type].ts` when there are multiple files of the same type
+- Use kebab-case for multi-word names: `jwt-token.service.ts`
+
+### Type and Interface Prefixes
+
+```typescript
+// Interfaces use 'I' prefix
+interface IHealthCheckOptions {
+  restOptions: { path: string };
+}
+
+interface IAuthService {
+  signIn(context: Context): Promise<void>;
+}
+
+// Type aliases use 'T' prefix
+type TSignInRequest = z.infer<typeof SignInRequestSchema>;
+type TRouteContext = Context<Env, Path, Input>;
+
+// Generic constraints
+type TTableSchemaWithId = { id: PgColumn };
+```
+
+### Binding Keys
+
+Use static class with `@app/[component]/[feature]` format:
+
+```typescript
+export class HealthCheckBindingKeys {
+  static readonly HEALTH_CHECK_OPTIONS = '@app/health-check/options';
+}
+
+export class SocketIOBindingKeys {
+  static readonly SOCKET_IO_INSTANCE = '@app/socket-io/instance';
+  static readonly SERVER_OPTIONS = '@app/socket-io/server-options';
+}
+```
+
+## Directory Structure
+
+### Component Organization
+
+```
+src/components/[feature]/
+├── index.ts              # Barrel exports
+├── component.ts          # IoC binding setup
+├── controller.ts         # Route handlers
+└── common/
+    ├── index.ts          # Barrel exports
+    ├── keys.ts           # Binding key constants
+    ├── types.ts          # Interfaces and types
+    └── rest-paths.ts     # Route path constants
+```
+
+### Complex Component (with multiple features)
+
+```
+src/components/auth/
+├── index.ts
+├── authenticate/
+│   ├── index.ts
+│   ├── component.ts
+│   ├── common/
+│   ├── controllers/
+│   ├── services/
+│   └── strategies/
+└── models/
+    ├── entities/         # Database models
+    └── requests/         # Request schemas
+```
+
+### Barrel Exports
+
+Every folder should have an `index.ts` that re-exports its contents:
+
+```typescript
+// components/health-check/index.ts
+export * from './common';
+export * from './component';
+export * from './controller';
+
+// components/health-check/common/index.ts
+export * from './keys';
+export * from './rest-paths';
+export * from './types';
+```
+
+## Constants Pattern
+
+**Prefer static classes over enums** for better tree-shaking and extensibility.
+
+### Basic Constants
+
+```typescript
+export class Authentication {
+  static readonly STRATEGY_BASIC = 'basic';
+  static readonly STRATEGY_JWT = 'jwt';
+  static readonly TYPE_BEARER = 'Bearer';
+}
+
+export class HealthCheckRestPaths {
+  static readonly ROOT = '/';
+  static readonly PING = '/ping';
+  static readonly METRICS = '/metrics';
+}
+```
+
+### Typed Constants with Validation
+
+For constants that need type extraction and runtime validation, use this pattern:
+
+```typescript
+import { TConstValue } from '@venizia/ignis-helpers';
+
+export class DocumentUITypes {
+  // 1. Define static readonly values
+  static readonly SWAGGER = 'swagger';
+  static readonly SCALAR = 'scalar';
+
+  // 2. Create a Set for O(1) validation lookup
+  static readonly SCHEME_SET = new Set([this.SWAGGER, this.SCALAR]);
+
+  // 3. Validation helper method
+  static isValid(value: string): boolean {
+    return this.SCHEME_SET.has(value);
+  }
+}
+
+// 4. Extract union type from class values
+export type TDocumentUIType = TConstValue<typeof DocumentUITypes>;
+// Result: 'swagger' | 'scalar'
+```
+
+**Full Example with Usage:**
+
+```typescript
+import { TConstValue } from '@venizia/ignis-helpers';
+
+export class UserStatuses {
+  static readonly ACTIVE = 'active';
+  static readonly INACTIVE = 'inactive';
+  static readonly PENDING = 'pending';
+  static readonly BANNED = 'banned';
+
+  static readonly SCHEME_SET = new Set([
+    this.ACTIVE,
+    this.INACTIVE,
+    this.PENDING,
+    this.BANNED,
+  ]);
+
+  static isValid(value: string): boolean {
+    return this.SCHEME_SET.has(value);
+  }
+
+  // Optional: get all values as array
+  static values(): string[] {
+    return [...this.SCHEME_SET];
+  }
+}
+
+// Type-safe union type
+export type TUserStatus = TConstValue<typeof UserStatuses>;
+// Result: 'active' | 'inactive' | 'pending' | 'banned'
+
+// Usage in interfaces
+interface IUser {
+  id: string;
+  status: TUserStatus; // Type-safe!
+}
+
+// Usage with validation
+function updateUserStatus(userId: string, status: string) {
+  if (!UserStatuses.isValid(status)) {
+    throw getError({
+      statusCode: HTTP.ResultCodes.RS_4.BadRequest,
+      message: `Invalid status: ${status}. Valid: ${UserStatuses.values().join(', ')}`,
+    });
+  }
+  // status is validated at runtime
+}
+```
+
+### Enum vs Static Class Comparison
+
+| Aspect | Static Class | TypeScript Enum |
+|--------|--------------|-----------------|
+| Tree-shaking | Full support | Partial (IIFE blocks it) |
+| Bundle size | Minimal | Larger (IIFE wrapper) |
+| Runtime validation | O(1) with `Set` | O(n) with `Object.values()` |
+| Type extraction | `TConstValue<typeof X>` → values | `keyof typeof X` → keys (not values!) |
+| Add methods | Yes | Not possible |
+| Compiled output | Clean class | IIFE wrapper |
+
+**Compiled JavaScript:**
+
+```typescript
+// Enum compiles to IIFE (not tree-shakable)
+var UserStatus;
+(function (UserStatus) {
+  UserStatus["ACTIVE"] = "active";
+})(UserStatus || (UserStatus = {}));
+
+// Static class compiles cleanly
+class UserStatuses { }
+UserStatuses.ACTIVE = 'active';
+```
+
+**Type Extraction Difference:**
+
+```typescript
+// Enum - extracts KEYS
+type T = keyof typeof UserStatus; // 'ACTIVE' | 'INACTIVE'
+
+// Static Class - extracts VALUES
+type T = TConstValue<typeof UserStatuses>; // 'active' | 'inactive'
+```
+
+**When to use `const enum`:** Only for numeric flags with no iteration needed (values are inlined, zero runtime). But doesn't work with `--isolatedModules`.
+
+**Verdict:** Use Static Class for 90% of cases - better tree-shaking, easy validation, type-safe values, extensible with methods.
+
+## Configuration Patterns
+
+### Default Options
+
+Every configurable class should define `DEFAULT_OPTIONS`:
+
+```typescript
+const DEFAULT_OPTIONS: IHealthCheckOptions = {
+  restOptions: { path: '/health' },
+};
+
+const DEFAULT_SERVER_OPTIONS: Partial<IServerOptions> = {
+  identifier: 'SOCKET_IO_SERVER',
+  path: '/io',
+  cors: {
+    origin: '*',
+    methods: ['GET', 'POST'],
+  },
+};
+```
+
+### Option Merging
+
+```typescript
+// In component constructor or binding
+const extraOptions = this.application.get<Partial<IServerOptions>>({
+  key: BindingKeys.SERVER_OPTIONS,
+  isOptional: true,
+}) ?? {};
+
+this.options = Object.assign({}, DEFAULT_OPTIONS, extraOptions);
+```
+
+### Constructor Validation
+
+Validate required options in the constructor:
+
+```typescript
+constructor(options: IJWTTokenServiceOptions) {
+  super({ scope: JWTTokenService.name });
+
+  if (!options.jwtSecret) {
+    throw getError({
+      statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
+      message: '[JWTTokenService] Invalid jwtSecret',
+    });
+  }
+
+  if (!options.applicationSecret) {
+    throw getError({
+      statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
+      message: '[JWTTokenService] Invalid applicationSecret',
+    });
+  }
+
+  this.options = options;
+}
+```
+
+## Logging Patterns
+
+### Method Context Prefix
+
+Always include class and method context in log messages:
+
+```typescript
+// Format: [ClassName][methodName] Message with %s placeholders
+this.logger.info('[binding] Asset storage bound | Key: %s | Type: %s', key, storageType);
+this.logger.debug('[authenticate] Token validated | User: %s', userId);
+this.logger.warn('[register] Skipping duplicate registration | Type: %s', opts.type);
+this.logger.error('[generate] Token generation failed | Error: %s', error.message);
+```
+
+### Structured Data
+
+Use format specifiers for structured logging:
+
+```typescript
+// %s - string, %d - number, %j - JSON object
+this.logger.info('[create] User created | ID: %s | Email: %s', user.id, user.email);
+this.logger.debug('[config] Server options: %j', this.serverOptions);
+```
+
+## Scope Naming
+
+Every class extending a base class should set its scope using `ClassName.name`:
+
+```typescript
+export class JWTTokenService extends BaseService {
+  constructor() {
+    super({ scope: JWTTokenService.name });
+  }
+}
+
+export class UserController extends BaseController {
+  constructor() {
+    super({ scope: UserController.name });
+  }
+}
+```
+
 ## Environment Variables Management
 
 Avoid using `process.env` directly in your business logic. Instead, use the `applicationEnvironment` helper and define your keys as constants. This ensures type safety and centralized management.
@@ -147,7 +495,8 @@ const retries = applicationEnvironment.get<number>(EnvironmentKeys.APP_ENV_MAX_R
 
 Use the `getError` helper and `HTTP` constants to throw consistent, formatted exceptions that the framework's error handler can process correctly.
 
-**Example:**
+### Basic Error
+
 ```typescript
 import { getError, HTTP } from '@venizia/ignis';
 
@@ -155,9 +504,225 @@ if (!record) {
   throw getError({
     statusCode: HTTP.ResultCodes.RS_4.NotFound,
     message: 'Record not found',
-    // Optional details
-    details: { id: requestedId }
+    details: { id: requestedId },
   });
 }
 ```
 
+### Error with Context
+
+Include class/method context in error messages:
+
+```typescript
+// Format: [ClassName][methodName] Descriptive message
+throw getError({
+  statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
+  message: '[JWTTokenService][generate] Failed to generate token',
+});
+
+throw getError({
+  statusCode: HTTP.ResultCodes.RS_4.Unauthorized,
+  message: '[AuthMiddleware][authenticate] Missing authorization header',
+});
+```
+
+### Validation Errors
+
+```typescript
+constructor(options: IServiceOptions) {
+  if (!options.apiKey) {
+    throw getError({
+      statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
+      message: '[PaymentService] Missing required apiKey configuration',
+    });
+  }
+}
+```
+
+### HTTP Status Code Categories
+
+| Category | Constant | Use Case |
+|----------|----------|----------|
+| Success | `HTTP.ResultCodes.RS_2.Ok` | Successful response |
+| Created | `HTTP.ResultCodes.RS_2.Created` | Resource created |
+| Bad Request | `HTTP.ResultCodes.RS_4.BadRequest` | Invalid input |
+| Unauthorized | `HTTP.ResultCodes.RS_4.Unauthorized` | Missing/invalid auth |
+| Forbidden | `HTTP.ResultCodes.RS_4.Forbidden` | Insufficient permissions |
+| Not Found | `HTTP.ResultCodes.RS_4.NotFound` | Resource not found |
+| Internal Error | `HTTP.ResultCodes.RS_5.InternalServerError` | Server errors |
+
+## Route Definition Patterns
+
+Ignis supports three methods for defining routes. Choose based on your needs:
+
+### Method 1: Config-Driven Routes
+
+Define route configurations as constants:
+
+```typescript
+// common/rest-paths.ts
+export class UserRestPaths {
+  static readonly ROOT = '/';
+  static readonly BY_ID = '/:id';
+  static readonly PROFILE = '/profile';
+}
+
+// common/route-configs.ts
+export const ROUTE_CONFIGS = {
+  [UserRestPaths.ROOT]: {
+    method: HTTP.Methods.GET,
+    path: UserRestPaths.ROOT,
+    responses: jsonResponse({
+      [HTTP.ResultCodes.RS_2.Ok]: UserListSchema,
+    }),
+  },
+  [UserRestPaths.BY_ID]: {
+    method: HTTP.Methods.GET,
+    path: UserRestPaths.BY_ID,
+    request: {
+      params: z.object({ id: z.string().uuid() }),
+    },
+    responses: jsonResponse({
+      [HTTP.ResultCodes.RS_2.Ok]: UserSchema,
+      [HTTP.ResultCodes.RS_4.NotFound]: ErrorSchema,
+    }),
+  },
+} as const;
+```
+
+### Method 2: Using `@api` Decorator
+
+```typescript
+@controller({ path: '/users' })
+export class UserController extends BaseController {
+
+  @api({ configs: ROUTE_CONFIGS[UserRestPaths.ROOT] })
+  list(context: TRouteContext<typeof ROUTE_CONFIGS[typeof UserRestPaths.ROOT]>) {
+    return context.json({ users: [] }, HTTP.ResultCodes.RS_2.Ok);
+  }
+
+  @api({ configs: ROUTE_CONFIGS[UserRestPaths.BY_ID] })
+  getById(context: TRouteContext<typeof ROUTE_CONFIGS[typeof UserRestPaths.BY_ID]>) {
+    const { id } = context.req.valid('param');
+    return context.json({ id, name: 'User' }, HTTP.ResultCodes.RS_2.Ok);
+  }
+}
+```
+
+### Method 3: Using `bindRoute` (Programmatic)
+
+```typescript
+@controller({ path: '/health' })
+export class HealthCheckController extends BaseController {
+  constructor() {
+    super({ scope: HealthCheckController.name });
+
+    this.bindRoute({ configs: ROUTE_CONFIGS['/'] }).to({
+      handler: context => context.json({ status: 'ok' }),
+    });
+  }
+}
+```
+
+### Method 4: Using `defineRoute` (Inline)
+
+```typescript
+@controller({ path: '/health' })
+export class HealthCheckController extends BaseController {
+  constructor() {
+    super({ scope: HealthCheckController.name });
+
+    this.defineRoute({
+      configs: ROUTE_CONFIGS['/ping'],
+      handler: context => {
+        const { message } = context.req.valid('json');
+        return context.json({ echo: message }, HTTP.ResultCodes.RS_2.Ok);
+      },
+    });
+  }
+}
+```
+
+### OpenAPI Schema Integration
+
+Use Zod with `.openapi()` for automatic documentation:
+
+```typescript
+const CreateUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+}).openapi({
+  description: 'Create user request body',
+  example: { email: 'user@example.com', name: 'John Doe' },
+});
+
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  name: z.string(),
+  createdAt: z.string().datetime(),
+}).openapi({
+  description: 'User response',
+});
+```
+
+## Type Inference Patterns
+
+### Zod Schema to Type
+
+```typescript
+// Define schema
+export const SignInRequestSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+
+// Infer type from schema
+export type TSignInRequest = z.infer<typeof SignInRequestSchema>;
+```
+
+### Const Assertion for Literal Types
+
+```typescript
+const ROUTE_CONFIGS = {
+  '/users': { method: 'GET', path: '/users' },
+  '/users/:id': { method: 'GET', path: '/users/:id' },
+} as const;
+
+// Type is now narrowed to literal values
+type RouteKey = keyof typeof ROUTE_CONFIGS; // '/users' | '/users/:id'
+```
+
+### Generic Type Constraints
+
+```typescript
+export class DefaultCRUDRepository<
+  Schema extends TTableSchemaWithId = TTableSchemaWithId
+> {
+  // Schema is constrained to have an 'id' column
+}
+
+export interface IAuthService<
+  SIRQ extends TSignInRequest = TSignInRequest,
+  SIRS = AnyObject,
+> {
+  signIn(context: Context, opts: SIRQ): Promise<SIRS>;
+}
+```
+
+## Summary Table
+
+| Aspect | Standard |
+|--------|----------|
+| Interface prefix | `I` (e.g., `IUserService`) |
+| Type alias prefix | `T` (e.g., `TUserRequest`) |
+| Class naming | PascalCase with suffix (e.g., `UserController`) |
+| File naming | kebab-case (e.g., `user.controller.ts`) |
+| Binding keys | `@app/[component]/[feature]` |
+| Constants | Static readonly class (not enums) |
+| Barrel exports | `index.ts` at every folder level |
+| Error format | `[ClassName][method] Message` |
+| Logging format | `[method] Message \| Key: %s` |
+| Default options | `DEFAULT_OPTIONS` constant |
+| Scope naming | `ClassName.name` |
+