@venizia/ignis-docs 0.0.1-8 → 0.0.1

package/wiki/references/base/components.md

@@ -1,6 +1,6 @@
 # Deep Dive: Components
 
-Technical reference for `BaseComponent` - creating pluggable, reusable modules in Ignis.
+Technical reference for `BaseComponent`—the foundation for creating reusable, pluggable features in Ignis. Components are powerful containers that can group together multiple providers, services, controllers, repositories, and even entire mini-applications into a single, redistributable module.
 
 **File:** `packages/core/src/base/components/base.ts`
 

package/wiki/references/base/controllers.md

@@ -65,7 +65,7 @@ export class MyFeatureController extends BaseController {
 
   @api({ configs: MyRouteConfig })
   getData(c: TRouteContext<typeof MyRouteConfig>) { // Return type is automatically inferred and validated
-    return c.json({ success: true });
+    return c.json({ success: true }, HTTP.ResultCodes.RS_2.Ok);
   }
 }
 ```
@@ -83,7 +83,7 @@ For convenience, `Ignis` provides decorator shortcuts for each HTTP method: Thes
 **Example using `@get` and `@post` with type inference:**
 
 ```typescript
-import { get, post, z, jsonContent, jsonResponse, Authentication, TRouteContext } from '@venizia/ignis';
+import { get, post, z, jsonContent, jsonResponse, Authentication, TRouteContext, HTTP } from '@venizia/ignis';
 
 // Define route configs as const for full type inference
 const USER_ROUTES = {
@@ -125,20 +125,20 @@ const USER_ROUTES = {
 
   @get({ configs: USER_ROUTES.listUsers })
   getAllUsers(c: TRouteContext<typeof USER_ROUTES.listUsers>) { // Return type is automatically inferred
-    return c.json([{ id: '1', name: 'John Doe' }]);
+    return c.json([{ id: '1', name: 'John Doe' }], HTTP.ResultCodes.RS_2.Ok);
   }
 
   @get({ configs: USER_ROUTES.getUser })
   getUserById(c: TRouteContext<typeof USER_ROUTES.getUser>) { // Return type is automatically inferred
     const { id } = c.req.valid('param'); // id is typed as string
-    return c.json({ id, name: 'John Doe' });
+    return c.json({ id, name: 'John Doe' }, HTTP.ResultCodes.RS_2.Ok);
   }
 
   @post({ configs: USER_ROUTES.createUser })
   createUser(c: TRouteContext<typeof USER_ROUTES.createUser>) { // Return type is automatically inferred
     const { name } = c.req.valid('json'); // name is typed as string
     const newUser = { id: '2', name };
-    return c.json(newUser, 201); // Return type is validated
+    return c.json(newUser, HTTP.ResultCodes.RS_2.Created); // Return type is validated
   }
 ```
 
@@ -171,17 +171,21 @@ export class HealthCheckController extends BaseController {
   @api({ configs: HEALTH_CHECK_ROUTES['/ping'] })
   ping(c: TRouteContext<typeof HEALTH_CHECK_ROUTES['/ping']>) { // Return type is automatically inferred
     const { message } = c.req.valid('json');
-    return c.json({ pong: message });
+    return c.json({ pong: message }, HTTP.ResultCodes.RS_2.Ok);
   }
 }
 ```
 
 ### Manual Route Definition Methods
 
-While decorator-based routing is available, the recommended way to define routes is by using the `defineRoute` and `bindRoute` methods inside the `binding()` method. This approach offers a clear and declarative syntax that keeps your route definitions organized and easy to manage.
+For advanced use cases or when you prefer a non-decorator approach, you can define routes manually using `defineRoute` and `bindRoute` methods inside the `binding()` method.
 
-:::tip Recommendation
-For better organization and a more declarative approach, we strongly recommend using `defineRoute` or `bindRoute` within the `binding()` method to define your controller's routes. This keeps all route definitions in one place, making your controller easier to read and maintain.
+:::tip When to Use Manual Definition
+Manual route definition is useful for:
+- Dynamically generating routes based on configuration
+- Conditional route registration (feature flags)
+- Developers who prefer non-decorator syntax (coming from Express/Fastify)
+- Complex routing logic that benefits from programmatic control
 :::
 
 #### `defineRoute`
@@ -291,17 +295,17 @@ This factory method returns a `BaseController` class that is already set up with
 
 **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 |
+| Route Name | Method | Path | Description |
 | :--- | :--- | :--- | :--- |
 | `count` | `GET` | `/count` | Get the number of records matching a filter. |
 | `find` | `GET` | `/` | Retrieve all records matching a filter. |
 | `findById` | `GET` | `/:id` | Retrieve a single record by its ID. |
 | `findOne` | `GET` | `/find-one` | Retrieve a single record matching a filter. |
 | `create` | `POST` | `/` | Create a new record. |
-| `updateById` | `PATCH` | `/:id` | Update a record by its ID. |
-| `updateAll` | `PATCH` | `/` | Update multiple records matching a filter. |
-| `deleteById` | `DELETE` | `/:id` | Delete a record by its ID. |
-| `deleteAll` | `DELETE` | `/` | Delete multiple records matching a filter. |
+| `updateById` | `PATCH` | `/:id` | Update a single record by its ID. |
+| `updateBy` | `PATCH` | `/` | Update multiple records matching a `where` filter. |
+| `deleteById` | `DELETE` | `/:id` | Delete a single record by its ID. |
+| `deleteBy` | `DELETE` | `/` | Delete multiple records matching a `where` filter. |
 
 ### `ICrudControllerOptions<EntitySchema>`
 
@@ -311,10 +315,30 @@ This factory method returns a `BaseController` class that is already set up with
 | `repository.name` | `string` | The binding key name of the repository associated with this entity (e.g., `'ConfigurationRepository'`). |
 | `controller.name` | `string` | A unique name for the generated controller (e.g., `'ConfigurationController'`). |
 | `controller.basePath`| `string` | The base path for all routes in this CRUD controller (e.g., `'/configurations'`). |
+| `controller.readonly` | `boolean` | If `true`, only read operations (find, findOne, findById, count) are generated. Write operations are excluded. Defaults to `false`. |
 | `controller.isStrict` | `boolean` | If `true`, query parameters like `where` will be strictly validated. Defaults to `true`. |
 | `controller.defaultLimit`| `number` | The default limit for `find` operations. Defaults to `10`. |
-| `schema` | `object` | An optional object to override the default Zod schemas for specific CRUD endpoints (e.g., `find`, `create`, `updateByIdRequestBody`). This allows for fine-grained control over the request and response validation and OpenAPI documentation. |
-| `doDeleteWithReturn` | `boolean` | If `true`, the `deleteById` and `deleteAll` endpoints will return the deleted record(s) in the response body. Defaults to `false`. |
+| `schema` | `object` | An optional object to override the default Zod schemas for specific CRUD endpoints. See schema options below. |
+| `doDeleteWithReturn` | `boolean` | If `true`, the `deleteById` and `deleteBy` endpoints will return the deleted record(s) in the response body. Defaults to `false`. |
+
+### Schema Override Options
+
+The `schema` option allows fine-grained control over request/response validation and OpenAPI documentation:
+
+| Schema Option | Description |
+| :--- | :--- |
+| `count` | Override response schema for count endpoint |
+| `find` | Override response schema for find endpoint |
+| `findOne` | Override response schema for findOne endpoint |
+| `findById` | Override response schema for findById endpoint |
+| `create` | Override response schema for create endpoint |
+| `createRequestBody` | Override request body schema for create endpoint |
+| `updateById` | Override response schema for updateById endpoint |
+| `updateByIdRequestBody` | Override request body schema for updateById endpoint |
+| `updateBy` | Override response schema for updateBy (bulk update) endpoint |
+| `updateByRequestBody` | Override request body schema for updateBy endpoint |
+| `deleteById` | Override response schema for deleteById endpoint |
+| `deleteBy` | Override response schema for deleteBy (bulk delete) endpoint |
 
 ### Example
 

package/wiki/references/base/datasources.md

@@ -8,9 +8,9 @@ Technical reference for DataSource classes - managing database connections in Ig
 
 | Class/Interface | Purpose | Key Members |
 |-----------------|---------|-------------|
-| **IDataSource** | Contract for all datasources | `name`, `settings`, `connector`, `schema`, `configure()` |
+| **IDataSource** | Contract for all datasources | `name`, `settings`, `connector`, `getSchema()`, `configure()` |
 | **AbstractDataSource** | Base implementation with logging | Extends `BaseHelper` |
-| **BaseDataSource** | Concrete class to extend | Constructor accepts `name`, `driver`, `config`, `schema` |
+| **BaseDataSource** | Concrete class to extend | Auto-discovery, driver from decorator |
 
 ## `IDataSource` Interface
 
@@ -25,7 +25,7 @@ Contract for all datasource classes in the framework.
 | `name` | `string` | Datasource name |
 | `settings` | `object` | Configuration object |
 | `connector` | `TDatabaseConnector` | Database connector instance (e.g., Drizzle) |
-| `schema` | `object` | Combined Drizzle schema (tables + relations) |
+| `getSchema()` | Method | Returns combined Drizzle schema (auto-discovered or manual) |
 | `configure()` | Method | Initializes the `connector` |
 | `getConnectionString()` | Method | Returns connection string |
 
@@ -39,29 +39,60 @@ This is the top-level abstract class that implements the `IDataSource` interface
 
 ### `BaseDataSource`
 
-This class extends `AbstractDataSource` and provides a constructor that standardizes how datasources are created. When you create your own datasource, you extend `BaseDataSource`.
+This class extends `AbstractDataSource` and provides a constructor with **auto-discovery** support. When you create your own datasource, you extend `BaseDataSource`.
 
-### Constructor and Configuration Flow
+#### Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Driver Auto-Read** | Driver is read from `@datasource` decorator - no need to pass in constructor |
+| **Schema Auto-Discovery** | Schema is automatically built from registered `@repository` decorators |
+| **Manual Override** | You can still manually provide schema in constructor for full control |
+
+### Constructor Options
+
+```typescript
+constructor(opts: {
+  name: string;           // DataSource name (usually class name)
+  config: Settings;       // Database connection settings
+  driver?: TDataSourceDriver;  // Optional - read from @datasource if not provided
+  schema?: Schema;        // Optional - auto-discovered if not provided
+})
+```
+
+### Schema Auto-Discovery
+
+When you use `@repository({ model: YourModel, dataSource: YourDataSource })`, the framework automatically:
+
+1. Registers the model-datasource binding in the MetadataRegistry
+2. When `getSchema()` is called, discovers all models bound to this datasource
+3. Builds the combined schema (tables + relations) automatically
+
+**This means you no longer need to manually merge tables and relations in the DataSource constructor!**
+
+### Configuration Flow
 
 1.  **Your DataSource's `constructor` is called**:
-    -   You call `super()` with the `name`, `driver`, `config` (connection settings), and the crucial `schema` object.
-    -   The `schema` object **must** contain all your Drizzle tables and `relations` definitions.
+    -   You call `super()` with `name` and `config`
+    -   Driver is automatically read from `@datasource` decorator
+    -   Schema is auto-discovered from `@repository` bindings (or manually provided)
 
 2.  **`Application.registerDataSources()` is called during startup**:
-    -   The application gets your `DataSource` instance from the DI container.
-    -   It calls the `configure()` method on your instance.
+    -   The application gets your `DataSource` instance from the DI container
+    -   It calls the `configure()` method on your instance
 
 3.  **Your `configure()` method runs**:
-    -   This is where you instantiate the Drizzle ORM.
-    -   You pass the `this.settings` (your config) and `this.schema` to Drizzle, creating the `this.connector`.
+    -   This is where you instantiate the Drizzle ORM
+    -   Use `this.getSchema()` to get the auto-discovered schema and pass to Drizzle
+
+### Example Implementations
 
-### Example Implementation
+#### Pattern 1: Auto-Discovery (Recommended)
+
+Simplest approach - schema is auto-discovered from repositories:
 
 ```typescript
 // src/datasources/postgres.datasource.ts
-import {
-  // ... import your models and relations
-} from '@/models/entities';
 import {
   BaseDataSource,
   datasource,
@@ -71,35 +102,166 @@ import {
 import { drizzle } from 'drizzle-orm/node-postgres';
 import { Pool } from 'pg';
 
-// Decorator to mark this class as a datasource for DI
-@datasource()
-export class PostgresDataSource extends BaseDataSource<
-  TNodePostgresConnector, // Type of the connector
-  IDSConfigs              // Type of the config object
-> {
+interface IDSConfigs {
+  host: string;
+  port: number;
+  database: string;
+  user: string;
+  password: string;
+}
+
+/**
+ * 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',
-      config: { /* ... connection details from environment ... */ },
-      schema: {
-        // Register all tables and relations here
-        usersTable,
-        configurationTable,
-        ...configurationRelations,
+      // Driver is read from @datasource decorator - no need to pass here!
+      config: {
+        host: process.env.APP_ENV_POSTGRES_HOST ?? 'localhost',
+        port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
+        database: process.env.APP_ENV_POSTGRES_DATABASE ?? 'mydb',
+        user: process.env.APP_ENV_POSTGRES_USERNAME ?? 'postgres',
+        password: process.env.APP_ENV_POSTGRES_PASSWORD ?? '',
       },
+      // NO schema property - auto-discovered from @repository bindings!
     });
   }
 
-  // This method is called by the application at startup
   override configure(): ValueOrPromise<void> {
-    this.connector = drizzle({
-      client: new Pool(this.settings),
-      schema: this.schema,
+    // 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 });
+  }
+}
+```
+
+With this pattern, when you define repositories:
+
+```typescript
+@repository({ model: User, dataSource: PostgresDataSource })
+export class UserRepository extends DefaultCRUDRepository<typeof User.schema> {}
+
+@repository({ model: Configuration, dataSource: PostgresDataSource })
+export class ConfigurationRepository extends DefaultCRUDRepository<typeof Configuration.schema> {}
+```
+
+The `PostgresDataSource.schema` will automatically include User and Configuration tables and their relations.
+
+#### Pattern 2: Manual Schema (Full Control)
+
+When you need explicit control over schema (e.g., subset of models, custom ordering):
+
+```typescript
+import {
+  User, userTable, userRelations,
+  Configuration, configurationTable, configurationRelations,
+} from '@/models/entities';
+
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+  constructor() {
+    super({
+      name: PostgresDataSource.name,
+      config: {
+        host: process.env.APP_ENV_POSTGRES_HOST ?? 'localhost',
+        port: +(process.env.APP_ENV_POSTGRES_PORT ?? 5432),
+        database: process.env.APP_ENV_POSTGRES_DATABASE ?? 'mydb',
+        user: process.env.APP_ENV_POSTGRES_USERNAME ?? 'postgres',
+        password: process.env.APP_ENV_POSTGRES_PASSWORD ?? '',
+      },
+      // Manually provide schema using spread syntax
+      schema: {
+        [User.TABLE_NAME]: userTable,
+        [Configuration.TABLE_NAME]: configurationTable,
+        ...userRelations.relations,
+        ...configurationRelations.relations,
+      },
     });
   }
-  // ...
+
+  override configure(): ValueOrPromise<void> {
+    // When schema is manually provided, getSchema() returns it directly
+    const client = new Pool(this.settings);
+    this.connector = drizzle({ client, schema: this.getSchema() });
+  }
 }
 ```
 
+### @datasource Decorator
+
+The `@datasource` decorator registers datasource metadata:
+
+```typescript
+@datasource({
+  driver: 'node-postgres',       // Required - database driver
+  autoDiscovery?: true           // Optional - defaults to true
+})
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `driver` | `TDataSourceDriver` | - | Database driver name |
+| `autoDiscovery` | `boolean` | `true` | Enable/disable schema auto-discovery |
+
+### Abstract Methods
+
+These methods must be implemented in your datasource class:
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `configure(opts?)` | `ValueOrPromise<void>` | Initialize the Drizzle ORM connector. Called during application startup. |
+| `getConnectionString()` | `ValueOrPromise<string>` | Return the database connection string. |
+
+### Optional Override Methods
+
+These methods can be optionally overridden for connection lifecycle management:
+
+| Method | Return Type | Description |
+|--------|-------------|-------------|
+| `connect()` | `Promise<Connector \| undefined>` | Establish database connection. Useful for connection pooling. |
+| `disconnect()` | `Promise<void>` | Close database connection gracefully. |
+
+```typescript
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+  // ... constructor and configure() ...
+
+  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();
+  }
+}
+```
+
+### Helper Methods
+
+| Method | Description |
+|--------|-------------|
+| `getSchema()` | Returns the schema (auto-discovers if not manually provided) |
+| `getSettings()` | Returns connection settings |
+| `getConnector()` | Returns the Drizzle connector |
+| `hasDiscoverableModels()` | Returns `true` if there are models registered for this datasource |
+
 This architecture ensures that datasources are configured consistently and that the fully-initialized Drizzle connector, aware of all schemas and relations, is available to repositories for querying.

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

@@ -4,24 +4,25 @@ Technical reference for the DI system in Ignis - managing resource lifecycles an
 
 **Files:**
 - `packages/inversion/src/container.ts` (base Container and Binding classes)
-- `packages/helpers/src/helpers/inversion/container.ts` (extended Container with ApplicationLogger)
+- `packages/core/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)
+- `packages/core/src/helpers/inversion/registry.ts` (MetadataRegistry)
 
 ## 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()` |
+| **Binding** | Single registered dependency configuration | `toClass()`, `toValue()`, `toProvider()`, `setScope()`, `setTags()` |
 | **@inject** | Decorator marking injection points | Applied to constructor parameters/properties |
 | **MetadataRegistry** | Stores decorator metadata | Singleton accessed via `getInstance()` |
+| **Boot System** | Automatic artifact discovery and binding | Integrates with Container via tags and bindings |
 
 ## `Container` Class
 
 Heart of the DI system - registry managing all application resources.
 
-**File:** `packages/inversion/src/container.ts`
+**File:** `packages/inversion/src/container.ts` (Base) & `packages/core/src/helpers/inversion/container.ts` (Extended)
 
 ### Key Methods
 
@@ -74,7 +75,7 @@ This entire process is managed by the framework when your application starts up,
 
 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`
+-   **File:** `packages/core/src/helpers/inversion/registry.ts`
 
 ### Role in DI
 
@@ -82,3 +83,95 @@ The `MetadataRegistry` is a crucial part of the DI and routing systems. It's a s
 -   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.
+
+## Boot System Integration
+
+The boot system (`@venizia/ignis-boot`) extends the DI container to support automatic artifact discovery and registration.
+
+### Key Bindings
+
+When boot system is enabled, the following bindings are created:
+
+| Binding Key | Type | Description |
+|-------------|------|-------------|
+| `@app/instance` | Value | The application container instance |
+| `@app/project_root` | Value | Absolute path to project root |
+| `@app/boot-options` | Value | Boot configuration options |
+| `bootstrapper` | Class (Singleton) | Main boot orchestrator |
+| `booter.DatasourceBooter` | Class (Tagged: 'booter') | Datasource discovery booter |
+| `booter.RepositoryBooter` | Class (Tagged: 'booter') | Repository discovery booter |
+| `booter.ServiceBooter` | Class (Tagged: 'booter') | Service discovery booter |
+| `booter.ControllerBooter` | Class (Tagged: 'booter') | Controller discovery booter |
+
+### Tag-based Discovery
+
+The boot system uses container tags for automatic discovery:
+
+```typescript
+// Register a booter with tag
+this.bind({ key: 'booter.CustomBooter' })
+  .toClass(CustomBooter)
+  .setTags('booter');
+
+// Find all booters
+const booterBindings = this.findByTag<IBooter>({ tag: 'booter' });
+```
+
+This pattern allows the `Bootstrapper` to automatically discover and execute all registered booters without explicit registration.
+
+### Artifact Bindings
+
+Once artifacts are discovered and loaded, they're bound using consistent patterns:
+
+```typescript
+// Controllers
+this.bind({ key: 'controllers.UserController' }).toClass(UserController);
+
+// Services
+this.bind({ key: 'services.UserService' }).toClass(UserService);
+
+// Repositories
+this.bind({ key: 'repositories.UserRepository' }).toClass(UserRepository);
+
+// Datasources
+this.bind({ key: 'datasources.PostgresDataSource' }).toClass(PostgresDataSource);
+```
+
+### Boot Lifecycle & DI
+
+The boot system integrates into the application lifecycle:
+
+1. **Application Constructor** - Binds boot infrastructure if `bootOptions` configured
+2. **initialize()** - Calls `boot()` which:
+   - Discovers booters from container (via `findByTag`)
+   - Instantiates booters (via `container.get()` or `binding.getValue()`)
+   - Executes boot phases (configure → discover → load)
+   - Each booter binds discovered artifacts to container
+3. **Post-Boot** - All artifacts available for dependency injection
+
+**Example Flow:**
+
+```typescript
+// 1. Boot discovers UserController.js file
+// 2. Boot loads UserController class
+// 3. Boot binds to container:
+app.bind({ key: 'controllers.UserController' }).toClass(UserController);
+
+// 4. Later, when UserController is instantiated:
+@injectable()
+class UserController {
+  constructor(
+    @inject({ key: 'services.UserService' }) 
+    private userService: UserService  // Auto-injected!
+  ) {}
+}
+```
+
+### Benefits
+
+- **Zero-configuration DI**: Artifacts auto-discovered and registered
+- **Convention-based**: Follow naming patterns, get DI for free
+- **Extensible**: Custom booters integrate seamlessly via tags
+- **Type-safe**: Full TypeScript support throughout boot process
+
+> **Learn More:** See [Bootstrapping Concepts](/get-started/core-concepts/bootstrapping.md) and [Boot Package Reference](/references/src-details/boot.md)