@venizia/ignis-docs 0.0.1-9 → 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/dependency-injection.md

@@ -13,9 +13,10 @@ Technical reference for the DI system in Ignis - managing resource lifecycles an
 | 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
 
@@ -81,4 +82,96 @@ The `MetadataRegistry` is a crucial part of the DI and routing systems. It's a s
 -   When you use a decorator (e.g., `@inject`), it calls a method on the `MetadataRegistry.getInstance()` to store information about the injection (like the binding key and target property/parameter).
 -   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.
+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)

package/wiki/references/base/services.md

@@ -58,7 +58,7 @@ Services are the core of your application's logic. They act as a bridge between
 ### Example
 
 ```typescript
-import { BaseService, inject } from '@venizia/ignis';
+import { BaseService, inject, getError } from '@venizia/ignis';
 import { UserRepository } from '../repositories/user.repository';
 import { TUser } from '../models/entities';
 
@@ -81,7 +81,7 @@ export class UserService extends BaseService {
     const user = await this.userRepository.findById({ id: userId });
 
     if (!user) {
-      throw new Error('User not found');
+      throw getError({ message: 'User not found' });
     }
 
     // 5. Returns transformed data

package/wiki/references/components/authentication.md

@@ -236,6 +236,7 @@ import {
   IJWTTokenPayload,
   JWTTokenService,
   TSignInRequest,
+  getError,
 } from '@venizia/ignis';
 import { Context } from 'hono';
 
@@ -256,7 +257,7 @@ export class AuthenticationService extends BaseService implements IAuthService {
     const user = { id: 'user-id-from-db', roles: [] }; // Dummy user
 
     if (identifier.value !== 'test_username' || credential.value !== 'test_password') {
-      throw new Error('Invalid credentials');
+      throw getError({ message: 'Invalid credentials' });
     }
     // --- End of custom logic ---
 
@@ -272,12 +273,12 @@ export class AuthenticationService extends BaseService implements IAuthService {
 
   async signUp(context: Context, opts: any): Promise<any> {
     // Implement your sign-up logic
-    throw new Error('Method not implemented.');
+    throw getError({ message: 'Method not implemented.' });
   }
 
   async changePassword(context: Context, opts: any): Promise<any> {
     // Implement your change password logic
-    throw new Error('Method not implemented.');
+    throw getError({ message: 'Method not implemented.' });
   }
 }
 ```

package/wiki/references/components/index.md

@@ -1,6 +1,6 @@
 # Components
 
-Reusable, pluggable modules that encapsulate specific features in Ignis applications.
+Reusable, pluggable modules that group together related features. A component can encapsulate various resources such as providers, services, controllers, repositories, or even an entire mini-application, providing a clean way to modularize and share complex logic across Ignis applications.
 
 ## Built-in Components
 

package/wiki/references/helpers/error.md

@@ -26,10 +26,10 @@ Extends native `Error` with HTTP status codes and machine-readable message codes
 You can create a new `ApplicationError` with a message, status code, and an optional message code.
 
 ```typescript
-import { ApplicationError, HTTP } from '@venizia/ignis';
+import { getError, HTTP } from '@venizia/ignis';
 
 // Throw an error for a resource not found
-throw new ApplicationError({
+throw getError({
   message: 'User not found',
   statusCode: HTTP.ResultCodes.RS_4.NotFound,
   messageCode: 'USER_NOT_FOUND',

package/wiki/references/src-details/boot.md

@@ -0,0 +1,379 @@
+# @venizia/ignis-boot
+
+> **Package**: `@venizia/ignis-boot`  
+> **Purpose**: Application bootstrapping system with artifact auto-discovery  
+> **Version**: 0.0.0
+
+## Overview
+
+The `@venizia/ignis-boot` package provides a powerful bootstrapping system that automatically discovers and loads application artifacts (controllers, services, repositories, datasources) during application startup. It eliminates the need for manual registration of each artifact, making application setup cleaner and more maintainable.
+
+## Key Concepts
+
+### Boot Phases
+
+The boot process consists of three phases executed in order:
+
+1. **Configure** - Booters configure their discovery patterns
+2. **Discover** - Booters scan filesystem for matching artifacts
+3. **Load** - Booters load classes and bind them to the application container
+
+### Artifacts
+
+An artifact is any application component that can be auto-discovered:
+- **Controllers** - REST/API endpoint handlers
+- **Services** - Business logic layer
+- **Repositories** - Data access layer
+- **Datasources** - Database connections
+
+### Booters
+
+Booters are specialized classes that handle discovery and loading of specific artifact types. Each booter:
+- Defines default discovery patterns (directories, file extensions)
+- Scans filesystem for matching files
+- Loads classes from discovered files
+- Binds loaded classes to application container
+
+## Core Components
+
+### Bootstrapper
+
+Orchestrates the entire boot process.
+
+| Feature | Description |
+|---------|-------------|
+| **Phase Execution** | Runs configure → discover → load phases |
+| **Booter Discovery** | Automatically finds all registered booters |
+| **Error Handling** | Catches and reports errors during boot |
+| **Performance Tracking** | Measures time taken for each phase |
+
+**Usage:**
+
+```typescript
+import { Bootstrapper, IBootExecutionOptions } from '@venizia/ignis-boot';
+
+const bootstrapper = app.get<Bootstrapper>({ key: 'bootstrapper' });
+await bootstrapper.boot({
+  phases: ['configure', 'discover', 'load'], // optional, default: all phases
+  booters: ['ControllerBooter', 'ServiceBooter'], // optional, default: all booters
+});
+```
+
+### BaseArtifactBooter
+
+Abstract base class for creating custom booters.
+
+| Method | Phase | Description |
+|--------|-------|-------------|
+| `configure()` | Configure | Sets up discovery patterns |
+| `discover()` | Discover | Scans filesystem for artifacts |
+| `load()` | Load | Loads classes and binds to container |
+| `getPattern()` | - | Generates glob pattern for file discovery |
+| `bind()` | - | Abstract method - implement to bind loaded classes |
+
+**Custom Booter Example:**
+
+```typescript
+import { BaseArtifactBooter, IBooterOptions } from '@venizia/ignis-boot';
+import { inject } from '@venizia/ignis-inversion';
+
+export class CustomBooter extends BaseArtifactBooter {
+  constructor(
+    @inject({ key: '@app/project_root' }) root: string,
+    @inject({ key: '@app/instance' }) private app: IApplication,
+    @inject({ key: '@app/boot-options' }) bootOptions: IBootOptions,
+  ) {
+    super({ 
+      scope: CustomBooter.name, 
+      root, 
+      artifactOptions: bootOptions.custom ?? {} 
+    });
+  }
+
+  protected getDefaultDirs(): string[] {
+    return ['custom'];
+  }
+
+  protected getDefaultExtensions(): string[] {
+    return ['.custom.js'];
+  }
+
+  protected async bind(): Promise<void> {
+    for (const cls of this.loadedClasses) {
+      this.app.bind({ key: `custom.${cls.name}` }).toClass(cls);
+    }
+  }
+}
+```
+
+### Built-in Booters
+
+#### ControllerBooter
+
+Auto-discovers and registers controllers.
+
+| Configuration | Default Value |
+|---------------|---------------|
+| **Directories** | `['controllers']` |
+| **Extensions** | `['.controller.js']` |
+| **Binding Pattern** | `controllers.{ClassName}` |
+
+#### ServiceBooter
+
+Auto-discovers and registers services.
+
+| Configuration | Default Value |
+|---------------|---------------|
+| **Directories** | `['services']` |
+| **Extensions** | `['.service.js']` |
+| **Binding Pattern** | `services.{ClassName}` |
+
+#### RepositoryBooter
+
+Auto-discovers and registers repositories.
+
+| Configuration | Default Value |
+|---------------|---------------|
+| **Directories** | `['repositories']` |
+| **Extensions** | `['.repository.js']` |
+| **Binding Pattern** | `repositories.{ClassName}` |
+
+#### DatasourceBooter
+
+Auto-discovers and registers datasources.
+
+| Configuration | Default Value |
+|---------------|---------------|
+| **Directories** | `['datasources']` |
+| **Extensions** | `['.datasource.js']` |
+| **Binding Pattern** | `datasources.{ClassName}` |
+
+### BootMixin
+
+Mixin that adds bootable capability to any application.
+
+**Features:**
+- Automatically binds default booters
+- Exposes `boot()` method
+- Configurable via `bootOptions`
+
+**Usage:**
+
+```typescript
+import { BootMixin } from '@venizia/ignis-boot';
+import { Container } from '@venizia/ignis-inversion';
+
+class MyApp extends BootMixin(Container) {
+  bootOptions = {
+    controllers: { 
+      dirs: ['private-controllers', 'public-controllers'],
+      extensions: ['.controller.js', '.controller.ts']
+    },
+    services: { 
+      isNested: true // scan subdirectories
+    }
+  };
+}
+
+const app = new MyApp();
+await app.boot();
+```
+
+## Boot Options
+
+Configure artifact discovery per artifact type.
+
+### IArtifactOptions
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `dirs` | `string[]` | Varies | Directories to scan |
+| `extensions` | `string[]` | Varies | File extensions to match |
+| `isNested` | `boolean` | `true` | Scan subdirectories |
+| `glob` | `string` | - | Custom glob pattern (overrides dirs/extensions) |
+
+### IBootOptions
+
+```typescript
+interface IBootOptions {
+  controllers?: IArtifactOptions;
+  services?: IArtifactOptions;
+  repositories?: IArtifactOptions;
+  datasources?: IArtifactOptions;
+  [artifactType: string]: IArtifactOptions | undefined;
+}
+```
+
+**Example Configuration:**
+
+```typescript
+const bootOptions: IBootOptions = {
+  controllers: {
+    dirs: ['controllers/private', 'controllers/public'],
+    extensions: ['.controller.js'],
+    isNested: true
+  },
+  repositories: {
+    glob: 'data-access/**/*.repository.js' // custom pattern
+  },
+  services: {
+    dirs: ['services'],
+    extensions: ['.service.js', '.service.ts'],
+    isNested: false // only scan root level
+  }
+};
+```
+
+## Integration with Core
+
+### BaseApplication Integration
+
+Boot system is integrated into `BaseApplication` via `IBootableApplication` interface:
+
+```typescript
+export abstract class BaseApplication 
+  extends AbstractApplication 
+  implements IRestApplication, IBootableApplication {
+  
+  bootOptions?: IBootOptions;
+  
+  boot(): Promise<IBootReport> {
+    const bootstrapper = this.get<Bootstrapper>({ key: 'bootstrapper' });
+    return bootstrapper.boot({});
+  }
+}
+```
+
+### Automatic Initialization
+
+If `bootOptions` is defined in application config, boot runs automatically during `initialize()`:
+
+```typescript
+override async initialize() {
+  if (this.configs.bootOptions) {
+    // Bind boot infrastructure
+    this.bind({ key: '@app/boot-options' }).toValue(this.bootOptions ?? {});
+    this.bind({ key: 'bootstrapper' }).toClass(Bootstrapper);
+    
+    // Register default booters
+    this.booter(DatasourceBooter);
+    this.booter(RepositoryBooter);
+    this.booter(ServiceBooter);
+    this.booter(ControllerBooter);
+    
+    // Execute boot
+    await this.boot();
+  }
+  
+  // ... rest of initialization
+}
+```
+
+## Utilities
+
+### discoverFiles
+
+Discovers files matching a glob pattern.
+
+```typescript
+const files = await discoverFiles({ 
+  pattern: 'controllers/**/*.controller.js',
+  root: '/path/to/project'
+});
+// Returns: ['/path/to/project/controllers/user.controller.js', ...]
+```
+
+### loadClasses
+
+Loads class constructors from files.
+
+```typescript
+const classes = await loadClasses({ 
+  files: ['/path/to/file1.js', '/path/to/file2.js'],
+  root: '/path/to/project'
+});
+// Returns: [UserController, ProductController, ...]
+```
+
+### isClass
+
+Type guard to check if value is a class constructor.
+
+```typescript
+if (isClass(exported)) {
+  // exported is TClass<any>
+}
+```
+
+## Complete Example
+
+```typescript
+import { BaseApplication, IApplicationConfigs } from '@venizia/ignis';
+import { IBootOptions } from '@venizia/ignis-boot';
+
+export const appConfigs: IApplicationConfigs = {
+  name: 'MyApp',
+  bootOptions: {
+    controllers: {
+      dirs: ['controllers'],
+      extensions: ['.controller.js'],
+      isNested: true
+    },
+    services: {
+      dirs: ['services'],
+      extensions: ['.service.js'],
+      isNested: true
+    },
+    repositories: {
+      dirs: ['repositories'],
+      extensions: ['.repository.js']
+    },
+    datasources: {
+      dirs: ['datasources'],
+      extensions: ['.datasource.js']
+    }
+  }
+};
+
+export class MyApp extends BaseApplication {
+  constructor() {
+    super(appConfigs);
+  }
+}
+
+// Boot runs automatically during initialize()
+const app = new MyApp();
+await app.start(); // Calls initialize() which triggers boot
+```
+
+## Benefits
+
+| Benefit | Description |
+|---------|-------------|
+| **Auto-discovery** | No manual registration of controllers/services/repositories |
+| **Convention-based** | Follow naming conventions, framework handles the rest |
+| **Flexible** | Customize discovery patterns per artifact type |
+| **Extensible** | Create custom booters for new artifact types |
+| **Performance** | Track boot time per phase |
+| **Developer Experience** | Focus on writing code, not wiring infrastructure |
+
+## When to Use
+
+✅ **Use Boot System When:**
+- Building applications with many controllers/services/repositories
+- Want convention-over-configuration approach
+- Need consistent artifact registration across projects
+- Building modular applications with clear folder structure
+
+❌ **Manual Registration When:**
+- Very small applications (< 5 artifacts)
+- Need fine-grained control over registration order
+- Dynamic artifact registration based on runtime conditions
+- Artifacts don't follow file naming conventions
+
+## Related Documentation
+
+- [Bootstrapping Concepts](/get-started/core-concepts/bootstrapping.md)
+- [Application Guide](/get-started/core-concepts/application.md)
+- [Dependency Injection](/references/base/dependency-injection.md)
+- [Core Package](/references/src-details/core.md)

package/wiki/references/src-details/core.md

@@ -52,8 +52,8 @@ This is the foundational layer of Ignis, defining the core architecture and abst
 | File/Folder   | Purpose/Key Details                                                                                                                                                                                                                                                                                       |
 | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `abstract.ts` | Defines `AbstractApplication`, the base class for Ignis applications. Handles core server setup (Hono instance, runtime detection for Bun/Node.js), environment validation, and route inspection. Mandates abstract methods for middleware setup and configuration.                                       |
-| `base.ts`     | Extends `AbstractApplication` to provide `BaseApplication`, implementing common functionalities like component, controller, service, repository, and datasource registration. Includes default middleware registration (e.g., error handling, favicon, request tracking) and startup information logging. |
-| `types.ts`    | Contains interfaces for application configurations (`IApplicationConfigs`), application information (`IApplicationInfo`), and various middleware options (e.g., `ICORSOptions`, `ICSRFOptions`).                                                                                                          |
+| `base.ts`     | Extends `AbstractApplication` to provide `BaseApplication`, implementing common functionalities like component, controller, service, repository, and datasource registration. Includes default middleware registration (e.g., error handling, favicon, request tracking) and startup information logging. Integrates with `@venizia/ignis-boot` for automatic artifact discovery when `bootOptions` is configured. |
+| `types.ts`    | Contains interfaces for application configurations (`IApplicationConfigs`), application information (`IApplicationInfo`), and various middleware options (e.g., `ICORSOptions`, `ICSRFOptions`). Now includes `IBootableApplication` interface for boot system integration. |
 
 #### `base/components`