@venizia/ignis-docs 0.0.1-8 → 0.0.1

package/wiki/get-started/best-practices/common-pitfalls.md

@@ -66,6 +66,8 @@ export class Application extends BaseApplication {
 
 -   **Bad:**
     ```typescript
+    import { ApplicationError, getError } from '@venizia/ignis';
+
     // In a Controller
     async createUser(c: Context) {
         const { name, email, companyName } = c.req.valid('json');
@@ -73,13 +75,13 @@ export class Application extends BaseApplication {
         // Complex logic inside the controller
         const existingUser = await this.userRepository.findByEmail(email);
         if (existingUser) {
-            throw new ApplicationError({ message: 'Email already exists' });
+            throw getError({ message: 'Email already exists' });
         }
         
         const company = await this.companyRepository.findOrCreate(companyName);
         const user = await this.userRepository.create({ name, email, companyId: company.id });
         
-        return c.json(user);
+        return c.json(user, HTTP.ResultCodes.RS_2.Ok);
     }
     ```
 -   **Good:**
@@ -89,7 +91,7 @@ export class Application extends BaseApplication {
         const userData = c.req.valid('json');
         // Delegate to the service
         const newUser = await this.userService.createUser(userData);
-        return c.json(newUser);
+        return c.json(newUser, HTTP.ResultCodes.RS_2.Ok);
     }
     
     // In UserService
@@ -101,7 +103,7 @@ export class Application extends BaseApplication {
     }
     ```
 
-### 4. Missing Environment Variables
+## 4. Missing Environment Variables
 
 **Pitfall:** The application fails to start or behaves unexpectedly because required environment variables are not defined in your `.env` file. The framework validates variables prefixed with `APP_ENV_` by default.
 
@@ -121,7 +123,7 @@ APP_ENV_POSTGRES_PASSWORD=password
 APP_ENV_POSTGRES_DATABASE=db
 ```
 
-### 5. Not Using `as const` for Route Definitions
+## 5. Not Using `as const` for Route Definitions
 
 **Pitfall:** When using the decorator-based routing with a shared `ROUTE_CONFIGS` object, you forget to add `as const` to the object definition. TypeScript will infer the types too broadly, and you will lose the benefits of type-safe contexts (`TRouteContext`).
 

package/wiki/get-started/best-practices/contribution-workflow.md

@@ -56,6 +56,7 @@ The project uses a Makefile for common development tasks:
 **Individual package builds:**
 ```bash
 make core          # Build @venizia/ignis (after dependencies)
+make boot          # Build @venizia/ignis-boot
 make helpers       # Build @venizia/ignis-helpers
 make inversion     # Build @venizia/ignis-inversion
 make dev-configs   # Build @venizia/dev-configs
@@ -65,6 +66,7 @@ make docs          # Build documentation
 **Force update individual packages:**
 ```bash
 make update-core
+make update-boot
 make update-helpers
 make update-inversion
 make update-dev-configs

package/wiki/get-started/best-practices/data-modeling.md

@@ -6,30 +6,24 @@ Ignis streamlines data modeling with Drizzle ORM by providing powerful helpers a
 
 All entity models should extend `BaseEntity`. This provides integration with the framework's repository layer and automatic schema generation support.
 
-**Example (`src/models/entities/configuration.model.ts`):**
+The recommended pattern is to define the schema and relations as **static properties** on the class. This keeps the definition self-contained and enables powerful type inference.
 
-```typescript
-import {
-  BaseEntity,
-  model,
-  TTableObject,
-} from '@venizia/ignis';
-import { configurationTable } from './schema'; // Your Drizzle schema
+**Example (`src/models/entities/user.model.ts`):**
 
-// Define types for TypeScript inference
-export type TConfigurationSchema = typeof configurationTable;
-export type TConfiguration = TTableObject<TConfigurationSchema>;
+```typescript
+import { BaseEntity, extraUserColumns, generateIdColumnDefs, model } from '@venizia/ignis';
+import { pgTable } from 'drizzle-orm/pg-core';
 
-@model({ type: 'entity', skipMigrate: false })
-export class Configuration extends BaseEntity<TConfigurationSchema> {
-  static readonly TABLE_NAME = Configuration.name;
+@model({ type: 'entity' })
+export class User extends BaseEntity<typeof User.schema> {
+  // 1. Define schema as a static property
+  static override schema = pgTable('User', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    ...extraUserColumns({ idType: 'string' }),
+  });
 
-  constructor() {
-    super({
-      name: Configuration.TABLE_NAME,
-      schema: configurationTable,
-    });
-  }
+  // 2. Define relations as a static method (return empty array if none)
+  static override relations = () => [];
 }
 ```
 
@@ -45,7 +39,7 @@ Instead of manually defining common columns like primary keys, timestamps, or au
 | `generateTzColumnDefs` | Adds timestamps | `createdAt`, `modifiedAt` (auto-updating) |
 | `generateUserAuditColumnDefs` | Adds audit fields | `createdBy`, `modifiedBy` |
 | `generateDataTypeColumnDefs` | Adds generic value fields | `nValue` (number), `tValue` (text), `jValue` (json), etc. |
-| `generatePrincipalColumnDefs` | Adds polymorphic relation fields | `principalType`, `principalId` |
+| `extraUserColumns` | Comprehensive user fields | Combines audit, timestamps, status, and type fields |
 
 **Usage Example:**
 
@@ -86,41 +80,98 @@ export const configurationTable = pgTable(
 
 ## 3. Defining Relations
 
-Use the `createRelations` helper to define relationships cleanly. This abstracts the Drizzle `relations` function and makes it easy to bind to repositories.
+Relations are defined using the `TRelationConfig` structure within the static `relations` method of your model.
 
-**Example:**
+**Example (`src/models/entities/configuration.model.ts`):**
 
 ```typescript
-import { createRelations, RelationTypes } from '@venizia/ignis';
-import { userTable } from './user.model';
+import {
+  BaseEntity,
+  model,
+  RelationTypes,
+  TRelationConfig,
+} from '@venizia/ignis';
+import { User } from './user.model';
+
+@model({ type: 'entity' })
+export class Configuration extends BaseEntity<typeof Configuration.schema> {
+  // ... schema definition ...
 
-export const configurationRelations = createRelations({
-  source: configurationTable,
-  relations: [
+  // Define relations
+  static override relations = (): TRelationConfig[] => [
     {
       name: 'creator',
       type: RelationTypes.ONE,
-      schema: userTable,
+      schema: User.schema,
       metadata: {
-        fields: [configurationTable.createdBy],
-        references: [userTable.id],
+        fields: [Configuration.schema.createdBy],
+        references: [User.schema.id],
       },
     },
-  ],
-});
+  ];
+}
 ```
 
-This configuration is then passed directly to your Repository:
+## 4. Repositories and Auto-Discovery
+
+Ignis simplifies the connection between models, repositories, and datasources.
+
+### DataSource Auto-Discovery
+
+DataSources automatically discover their schema from the repositories that bind to them. You **do not** need to manually register schemas in the DataSource constructor.
 
 ```typescript
-@repository({})
-export class ConfigurationRepository extends DefaultCRUDRepository<TConfigurationSchema> {
-  constructor(@inject({ key: 'datasources.PostgresDataSource' }) dataSource: IDataSource) {
+// src/datasources/postgres.datasource.ts
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+  constructor() {
     super({
-      dataSource,
-      entityClass: Configuration,
-      relations: configurationRelations.definitions, // <-- Injected here
+      name: PostgresDataSource.name,
+      config: { /* connection config */ },
+      // NO schema property needed - auto-discovered!
     });
   }
+
+  override configure(): ValueOrPromise<void> {
+    // This method automatically collects all schemas from bound repositories
+    const schema = this.getSchema();
+    this.connector = drizzle({ client: new Pool(this.settings), schema });
+  }
+}
+```
+
+### Repository Binding
+
+Repositories use the `@repository` decorator to bind a **Model** to a **DataSource**. This binding is what powers the auto-discovery mechanism.
+
+**Pattern 1: Zero Boilerplate (Recommended)**
+
+For most repositories, you don't need a constructor. The DataSource is automatically injected.
+
+```typescript
+@repository({ model: Configuration, dataSource: PostgresDataSource })
+export class ConfigurationRepository extends DefaultCRUDRepository<typeof Configuration.schema> {
+  // No constructor needed!
 }
 ```
+
+**Pattern 2: Explicit Injection (Advanced)**
+
+If you need to perform custom initialization or inject additional dependencies, you can define a constructor. **Important:** The first parameter must be the DataSource.
+
+```typescript
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends ReadableRepository<typeof User.schema> {
+  constructor(
+    @inject({ key: 'datasources.PostgresDataSource' })
+    dataSource: PostgresDataSource,
+  ) {
+    super(dataSource);
+  }
+
+  // Custom methods
+  async findByRealm(realm: string) {
+    return this.findOne({ filter: { where: { realm } } });
+  }
+}
+```

package/wiki/get-started/best-practices/security-guidelines.md

@@ -72,9 +72,11 @@ const SecureRoute = {
 
 **Access user in protected routes:**
 ```typescript
+import { Authentication, IJWTTokenPayload, ApplicationError, getError } from '@venizia/ignis';
+
 const user = c.get(Authentication.CURRENT_USER) as IJWTTokenPayload;
 if (!user.roles.includes('admin')) {
-    throw new ApplicationError({ statusCode: 403, message: 'Forbidden' });
+    throw getError({ statusCode: 403, message: 'Forbidden' });
 }
 ```
 

package/wiki/get-started/building-a-crud-api.md

@@ -134,12 +134,10 @@ export type TTodo = TTableObject<TTodoSchema>;
 
 // 4. Create the Entity class, decorated with @model
 @model({ type: 'entity' })
-export class Todo extends BaseEntity<TTodoSchema> {
-  static readonly TABLE_NAME = 'Todo';
-
-  constructor() {
-    super({ name: Todo.TABLE_NAME, schema: todoTable });
-  }
+export class Todo extends BaseEntity<typeof Todo.schema> {
+  static override schema = todoTable;
+  static override relations = () => todoRelations.definitions;
+  static override TABLE_NAME = 'Todo';
 }
 ```
 
@@ -203,7 +201,6 @@ Create `src/datasources/postgres.datasource.ts`:
 
 ```typescript
 // src/datasources/postgres.datasource.ts
-import { Todo, todoRelations, todoTable } from '@/models/todo.model';
 import {
   BaseDataSource,
   datasource,
@@ -214,61 +211,61 @@ import { drizzle } from 'drizzle-orm/node-postgres';
 import { Pool } from 'pg';
 
 interface IDSConfigs {
-  connection: {
-    host?: string;
-    port?: number;
-    user?: string;
-    password?: string;
-    database?: string;
-  };
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: string;
 }
 
-@datasource()
+/**
+ * PostgresDataSource with auto-discovery support.
+ *
+ * How it works:
+ * 1. @repository decorator binds model to datasource
+ * 2. When configure() is called, getSchema() auto-discovers all bound models
+ * 3. Drizzle is initialized with the auto-discovered schema
+ */
+@datasource({ driver: 'node-postgres' })
 export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
-      driver: 'node-postgres',
+      // Driver is read from @datasource decorator - no need to pass here!
       config: {
-        connection: {
-          host: process.env.APP_ENV_POSTGRES_HOST,
-          port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
-          user: process.env.APP_ENV_POSTGRES_USERNAME,
-          password: process.env.APP_ENV_POSTGRES_PASSWORD,
-          database: process.env.APP_ENV_POSTGRES_DATABASE,
-        },
+        host: process.env.APP_ENV_POSTGRES_HOST ?? 'localhost',
+        port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
+        database: process.env.APP_ENV_POSTGRES_DATABASE ?? 'todo_db',
+        user: process.env.APP_ENV_POSTGRES_USERNAME ?? 'postgres',
+        password: process.env.APP_ENV_POSTGRES_PASSWORD ?? '',
       },
-      // Register all your models and their relations here
-      schema: Object.assign(
-        {},
-        { [Todo.TABLE_NAME]: todoTable },
-        todoRelations.relations,
-      ),
+      // NO schema property - auto-discovered from @repository bindings!
     });
   }
 
   override configure(): ValueOrPromise<void> {
-    this.connector = drizzle({
-      client: new Pool(this.settings.connection),
-      schema: this.schema,
-    });
-  }
-
-  override async connect(): Promise<TNodePostgresConnector | undefined> {
-    await (this.connector.client as Pool).connect();
-    return this.connector;
-  }
-
-  override async disconnect(): Promise<void> {
-    await (this.connector.client as Pool).end();
+    // getSchema() auto-discovers models from @repository bindings
+    const schema = this.getSchema();
+
+    // Log discovered schema for debugging
+    const schemaKeys = Object.keys(schema);
+    this.logger.debug(
+      '[configure] Auto-discovered schema | Schema + Relations (%s): %o',
+      schemaKeys.length,
+      schemaKeys,
+    );
+
+    const client = new Pool(this.settings);
+    this.connector = drizzle({ client, schema });
   }
 }
 ```
 
 **Key Points:**
-- Registers `todoTable` and `todoRelations` in the schema
+- Schema is auto-discovered from `@repository` decorators - no manual registration needed
+- Uses `getSchema()` for lazy schema resolution (resolves when all models are loaded)
 - Uses environment variables for connection config
-- Implements connection lifecycle methods
+- Implements connection lifecycle methods (`connect()`, `disconnect()`)
 
 > **Deep Dive:** See [DataSources Reference](../references/base/datasources.md) for advanced configuration and multiple database support.
 
@@ -280,26 +277,15 @@ Create `src/repositories/todo.repository.ts`:
 
 ```typescript
 // src/repositories/todo.repository.ts
-import { Todo, todoRelations, TTodoSchema } from '@/models/todo.model';
-import {
-  DefaultCRUDRepository,
-  IDataSource,
-  inject,
-  repository,
-} from '@venizia/ignis';
-
-@repository()
-export class TodoRepository extends DefaultCRUDRepository<TTodoSchema> {
-  constructor(
-    @inject({ key: 'datasources.PostgresDataSource' })
-    dataSource: IDataSource,
-  ) {
-    super({
-      dataSource,
-      entityClass: Todo,
-      relations: todoRelations.definitions,
-    });
-  }
+import { Todo } from '@/models/todo.model';
+import { PostgresDataSource } from '@/datasources/postgres.datasource';
+import { DefaultCRUDRepository, repository } from '@venizia/ignis';
+
+// Both 'model' and 'dataSource' are required for schema auto-discovery
+@repository({ model: Todo, dataSource: PostgresDataSource })
+export class TodoRepository extends DefaultCRUDRepository<typeof Todo.schema> {
+  // No constructor needed! DataSource and relations are auto-resolved
+  // from the @repository decorator and entity's static properties
 }
 ```
 
@@ -358,15 +344,15 @@ export class TodoController extends _Controller {
 **Auto-generated Endpoints:**
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/todos` | List all todos |
-| GET | `/todos/:id` | Get todo by ID |
-| GET | `/todos/find-one` | Find one todo by filter |
-| GET | `/todos/count` | Count todos |
-| POST | `/todos` | Create todo |
-| PATCH | `/todos/:id` | Update todo by ID |
-| PATCH | `/todos` | Update multiple todos |
-| DELETE | `/todos/:id` | Delete todo by ID |
-| DELETE | `/todos` | Delete multiple todos |
+| GET | `/todos` | List all todos (find) |
+| GET | `/todos/:id` | Get todo by ID (findById) |
+| GET | `/todos/find-one` | Find one todo by filter (findOne) |
+| GET | `/todos/count` | Count todos (count) |
+| POST | `/todos` | Create todo (create) |
+| PATCH | `/todos/:id` | Update todo by ID (updateById) |
+| PATCH | `/todos` | Update multiple todos by filter (updateBy) |
+| DELETE | `/todos/:id` | Delete todo by ID (deleteById) |
+| DELETE | `/todos` | Delete multiple todos by filter (deleteBy) |
 
 > **Deep Dive:** See [ControllerFactory Reference](../references/base/controllers.md#controllerfactory) for customization options.
 
@@ -639,8 +625,7 @@ Now that you've built the Todo API, try building a **User** feature on your own!
 
 **Challenge checklist:**
 - [ ] Create `src/models/user.model.ts`
-- [ ] Update `PostgresDataSource` to include User schema
-- [ ] Create `src/repositories/user.repository.ts`
+- [ ] Create `src/repositories/user.repository.ts` (this auto-registers User with PostgresDataSource)
 - [ ] Create `src/controllers/user.controller.ts`
 - [ ] Register repository and controller in `application.ts`
 - [ ] Run migration: `bun run migrate:dev`
@@ -660,7 +645,7 @@ For complex validation or business rules, create a Service layer:
 
 ```typescript
 // src/services/todo.service.ts
-import { BaseService, inject } from '@venizia/ignis';
+import { BaseService, inject, getError } from '@venizia/ignis';
 import { TodoRepository } from '@/repositories/todo.repository';
 
 export class TodoService extends BaseService {
@@ -674,7 +659,7 @@ export class TodoService extends BaseService {
   async createTodo(data: any) {
     // Business logic validation
     if (data.title.length < 3) {
-      throw new Error('Title too short');
+      throw getError({ message: 'Title too short' });
     }
 
     // Check for duplicates
@@ -682,7 +667,7 @@ export class TodoService extends BaseService {
       filter: { where: { title: data.title } },
     });
     if (existing) {
-      throw new Error('Todo already exists');
+      throw getError({ message: 'Todo already exists' });
     }
 
     return this.todoRepository.create({ data });

package/wiki/get-started/core-concepts/application.md

@@ -42,10 +42,13 @@ export class Application extends BaseApplication {
   }
   
   preConfigure(): ValueOrPromise<void> {
-    // Register all your resources here
+    // Manual registration (traditional approach)
     this.dataSource(MyDataSource);
     this.service(MyService);
     this.controller(MyController);
+    
+    // Or use boot system for auto-discovery (recommended for larger apps)
+    // See Bootstrapping section below
   }
   
   postConfigure(): ValueOrPromise<void> {
@@ -75,10 +78,74 @@ The `BaseApplication` class provides several **overridable hook methods** that a
 | :--- | :--- |
 | `getAppInfo()` | **Required.** Return application metadata, usually from `package.json`. Used for OpenAPI docs. |
 | `staticConfigure()` | Configure static file serving. |
-| `preConfigure()` | **Most Important Hook.** Set up application resources like components, controllers, services, and datasources. |
+| `preConfigure()` | **Most Important Hook.** Set up application resources like components, controllers, services, and datasources. Can be skipped if using boot system. |
 | `postConfigure()` | Perform actions *after* all resources have been configured and instantiated. |
 | `setupMiddlewares()`| Add custom application-level middlewares to the Hono instance. |
 
+## Bootstrapping (Auto-discovery)
+
+The boot system provides automatic artifact discovery and loading, eliminating manual registration. When enabled, it scans your project directory and automatically loads controllers, services, repositories, and datasources.
+
+> **Detailed Guide:** See [Bootstrapping Concepts](./bootstrapping.md) for complete documentation.
+
+### Enabling Boot System
+
+Add `bootOptions` to your application config:
+
+```typescript
+export const appConfigs: IApplicationConfigs = {
+  host: process.env.APP_ENV_SERVER_HOST,
+  port: +(process.env.APP_ENV_SERVER_PORT ?? 3000),
+  // Enable boot system
+  bootOptions: {
+    datasources: { dirs: ['datasources'] },
+    repositories: { dirs: ['repositories'] },
+    services: { dirs: ['services'] },
+    controllers: { dirs: ['controllers'] }
+  }
+};
+```
+
+With boot enabled, you can skip manual registration in `preConfigure()`:
+
+```typescript
+export class Application extends BaseApplication {
+  // No need to register artifacts manually!
+  // Boot system handles it automatically
+  
+  preConfigure(): ValueOrPromise<void> {
+    // Only register things that need custom configuration
+    // Everything else is auto-discovered
+  }
+}
+```
+
+### Boot vs Manual Registration
+
+| Approach | Use Case | Pros | Cons |
+|----------|----------|------|------|
+| **Boot System** | Apps with 10+ artifacts per type | Auto-discovery, scalable, clean code | Requires file naming conventions |
+| **Manual Registration** | Small apps (< 5 artifacts) | Fine-grained control, explicit | Tedious, maintenance burden |
+
+### Project Structure for Boot
+
+Follow naming conventions for auto-discovery:
+
+```
+src/
+├── datasources/
+│   └── postgres.datasource.js
+├── repositories/
+│   ├── user.repository.js
+│   └── product.repository.js
+├── services/
+│   ├── auth.service.js
+│   └── user.service.js
+└── controllers/
+    ├── auth.controller.js
+    └── user.controller.js
+```
+
 ## Lifecycle Diagram
 
 This diagram shows the sequence of operations during application startup. The methods you can override are highlighted.
@@ -90,7 +157,8 @@ graph TD
     
     subgraph "initialize() Sequence"
         direction TB
-        B --> B1["printStartUpInfo"];
+        B --> B0["boot() - if bootOptions configured"];
+        B0 --> B1["printStartUpInfo"];
         B1 --> B2["validateEnvs"];
         B2 --> B3["registerDefaultMiddlewares"];
         B3 --> B4["staticConfigure()"];
@@ -129,6 +197,7 @@ Application configuration is passed to the `BaseApplication` constructor via an
 | `path.isStrict`| `boolean`| `true` | If `true`, the router is strict about trailing slashes. |
 | `debug.showRoutes`| `boolean`| `false`| If `true`, prints all registered routes to the console on startup. |
 | `favicon` | `string` | `'🔥'` | An emoji to be used as the application's favicon. |
+| `bootOptions` | `IBootOptions` | `undefined` | Enable auto-discovery of artifacts. See [Bootstrapping](./bootstrapping.md). |
 
 ### Example Configuration