@venizia/ignis-docs 0.0.1-9 → 0.0.2

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

@@ -6,26 +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.
+
+**Example (`src/models/entities/user.model.ts`):**
 
 ```typescript
-import {
-  BaseEntity,
-  model,
-  TTableObject,
-} from '@venizia/ignis';
-import { configurationTable, configurationRelations } from './schema'; // Your Drizzle schema
+import { BaseEntity, extraUserColumns, generateIdColumnDefs, model } from '@venizia/ignis';
+import { pgTable } from 'drizzle-orm/pg-core';
 
-// Define types for TypeScript inference
-export type TConfigurationSchema = typeof configurationTable;
-export type TConfiguration = TTableObject<TConfigurationSchema>;
+@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' }),
+  });
 
-@model({ type: 'entity', skipMigrate: false })
-export class Configuration extends BaseEntity<typeof Configuration.schema> {
-  // Use static properties (recommended pattern)
-  static override schema = configurationTable;
-  static override relations = () => configurationRelations.definitions;
-  static override TABLE_NAME = 'Configuration';
+  // 2. Define relations as a static method (return empty array if none)
+  static override relations = () => [];
 }
 ```
 
@@ -41,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:**
 
@@ -82,39 +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 automatically used when you define your Repository with the `@repository` decorator:
+## 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
-import { PostgresDataSource } from '@/datasources';
+// src/datasources/postgres.datasource.ts
+@datasource({ driver: 'node-postgres' })
+export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+  constructor() {
+    super({
+      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)**
 
-// Both 'model' and 'dataSource' are required for schema auto-discovery
+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! DataSource and relations are auto-resolved
-  // from the @repository decorator and entity's static properties
+  // 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

@@ -645,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 {
@@ -659,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
@@ -667,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