@venizia/ignis-docs 0.0.8-3 → 0.1.0

package/content/references/base/services.md

@@ -0,0 +1,404 @@
+---
+title: Services Reference
+description: Technical reference for BaseService and the business logic layer in IGNIS
+difficulty: beginner
+---
+
+# Deep Dive: Services
+
+Technical reference for `BaseService` - the foundation for the business logic layer in IGNIS.
+
+**File:** `packages/core/src/base/services/base.ts`
+
+## Quick Reference
+
+| Feature | Detail |
+|---------|--------|
+| **Import** | `import { BaseService, inject } from '@venizia/ignis'` |
+| **Extends** | `BaseHelper` from `@venizia/ignis-helpers` |
+| **Logging** | `this.logger` (scoped to constructor `scope`) |
+| **Registration** | `this.service(MyService)` in application lifecycle |
+| **Binding key** | `services.{ClassName}` (e.g., `services.AuthenticationService`) |
+| **DI decorator** | `@injectable` is NOT used on services - registration is imperative only |
+| **CRUD service** | Removed - use `DefaultCRUDRepository` for data access |
+
+---
+
+## `BaseService` Class
+
+Abstract class that all application services must extend.
+
+```typescript
+// packages/core/src/base/services/base.ts
+import { BaseHelper } from '@venizia/ignis-helpers';
+import { IService } from './types';
+
+export abstract class BaseService extends BaseHelper implements IService {
+  constructor(opts: { scope: string }) {
+    super({ scope: opts.scope });
+  }
+}
+```
+
+`BaseHelper` wires a scoped logger at `this.logger`. Pass `scope: ClassName.name` so log lines are tagged with the service name.
+
+### `IService` Interface
+
+Marker interface with no required methods - it exists purely for type-level contracts:
+
+```typescript
+export interface IService {}
+```
+
+---
+
+## Registering a Service
+
+Services are registered imperatively in an application lifecycle method. There is no `@injectable` or `@service` decorator used on service classes in application code - `this.service()` handles everything.
+
+```typescript
+// In your Application class (e.g., in preConfigure())
+this.service(AuthenticationService);  // binds as 'services.AuthenticationService'
+this.service(GreeterService);         // binds as 'services.GreeterService'
+```
+
+`this.service(Ctor)` is implemented directly on `BaseApplication`:
+
+```typescript
+// packages/core/src/base/applications/base.ts
+service<Base extends IService, Args extends AnyObject = any>(
+  ctor: TClass<Base>,
+  opts?: TMixinOpts<Args>,
+): Binding<Base> {
+  return this.bind<Base>({
+    key: BindingKeys.build(
+      opts?.binding ?? {
+        namespace: BindingNamespaces.SERVICE, // 'services'
+        key: ctor.name,                       // class name
+      },
+    ),
+  }).toClass(ctor);
+}
+```
+
+The resulting binding key defaults to `services.{ClassName}` (overridable via `opts.binding`).
+
+### Lifecycle Placement
+
+Register services before anything that depends on them. The correct hook is `preConfigure()`, or a private helper called from `preConfigure()`:
+
+```typescript
+export class Application extends BaseApplication {
+  preConfigure(): void {
+    // DataSources and repositories that services depend on must come first
+    this.dataSource(PostgresDataSource);
+    this.repository(UserRepository);
+
+    // Then register services
+    this.service(AuthenticationService);
+  }
+}
+```
+
+---
+
+## Dependency Injection into Services
+
+Inject repositories, other services, or datasources via `@inject` in the constructor. Two equivalent key forms are available:
+
+### String-literal keys
+
+```typescript
+import { BaseService, inject } from '@venizia/ignis';
+import { UserRepository } from '../repositories';
+import { JWKSIssuerTokenService } from '@venizia/ignis';
+
+export class AuthenticationService extends BaseService {
+  constructor(
+    @inject({ key: 'repositories.UserRepository' })
+    private userRepository: UserRepository,
+
+    @inject({ key: 'services.JWKSIssuerTokenService' })
+    private jwksTokenService: JWKSIssuerTokenService,
+  ) {
+    super({ scope: AuthenticationService.name });
+  }
+}
+```
+
+### Programmatic keys with `BindingKeys.build`
+
+`BindingKeys.build({ namespace, key })` produces the same `namespace.key` string. Use this form when you want a compile-time reference to a class name rather than a plain string:
+
+```typescript
+import { BaseService, BindingKeys, BindingNamespaces, inject } from '@venizia/ignis';
+import { UserRepository } from '../repositories';
+
+export class AuthenticationService extends BaseService {
+  constructor(
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.REPOSITORY,   // 'repositories'
+        key: UserRepository.name,                  // 'UserRepository'
+      }),
+    })
+    private userRepository: UserRepository,
+  ) {
+    super({ scope: AuthenticationService.name });
+  }
+}
+```
+
+Both forms produce identical binding keys at runtime. The `BindingKeys.build` form avoids typo risk when the class name changes.
+
+### Available `BindingNamespaces`
+
+| Constant | Value |
+|----------|-------|
+| `BindingNamespaces.SERVICE` | `'services'` |
+| `BindingNamespaces.REPOSITORY` | `'repositories'` |
+| `BindingNamespaces.DATASOURCE` | `'datasources'` |
+| `BindingNamespaces.CONTROLLER` | `'controllers'` |
+| `BindingNamespaces.COMPONENT` | `'components'` |
+| `BindingNamespaces.PROVIDER` | `'providers'` |
+
+---
+
+## Logging
+
+`BaseService` inherits `this.logger` from `BaseHelper`. Log with method scope for structured output:
+
+```typescript
+export class AuthenticationService extends BaseService {
+  async signIn(opts: { identifier: string }): Promise<string> {
+    // Method-scoped log - produces tag "[signIn]" in log output
+    this.logger.for('signIn').info('SignIn called | identifier: %s', opts.identifier);
+
+    // ... business logic ...
+
+    this.logger.for('signIn').info('SignIn successful');
+    return token;
+  }
+}
+```
+
+Use `this.logger.for('methodName')` to scope log lines to the current method. This matches the project-wide convention seen in all examples.
+
+---
+
+## Service-to-Service Composition
+
+Services can inject other services to compose business logic. Inject them the same way as repositories, using the `services.*` namespace:
+
+```typescript
+import { BaseService, BindingKeys, BindingNamespaces, inject } from '@venizia/ignis';
+
+export class OrderService extends BaseService {
+  constructor(
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.REPOSITORY,
+        key: OrderRepository.name,
+      }),
+    })
+    private orderRepository: OrderRepository,
+
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.REPOSITORY,
+        key: InventoryRepository.name,
+      }),
+    })
+    private inventoryRepository: InventoryRepository,
+
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.SERVICE,
+        key: NotificationService.name,
+      }),
+    })
+    private notificationService: NotificationService,
+  ) {
+    super({ scope: OrderService.name });
+  }
+
+  async createOrder(opts: { userId: string; items: OrderItem[] }): Promise<Order> {
+    this.logger.for('createOrder').info('Creating order | userId: %s', opts.userId);
+
+    const { data: order } = await this.orderRepository.create({ data: opts });
+
+    // Compose with another service
+    await this.notificationService.sendOrderConfirmation({ orderId: order.id });
+
+    return order;
+  }
+}
+```
+
+Register both services in `preConfigure()`:
+
+```typescript
+this.service(NotificationService);
+this.service(OrderService);
+```
+
+### Abstract Base Services
+
+For shared dependencies across multiple related services, define an abstract base. The container only ever `instantiate()`s the **concrete** class (`this.service(UserAuditTestService)` registers `UserAuditTestService`, never `BaseTestService`), and the hard DI rule - every constructor parameter of a container-instantiated class must carry `@inject` - applies to that concrete constructor. A `scope: string` computed from `ClassName.name` is not something the container can supply anyway, so it cannot sit as a bare constructor parameter next to an `@inject`-decorated one. The shared repository is injected as a **property** on the base instead, and the concrete subclass's constructor is left with zero parameters - nothing to decorate, nothing to violate:
+
+```typescript
+// Shared repository access for a group of test services - property injection,
+// so the concrete subclass's constructor stays free of undecorated parameters
+export abstract class BaseTestService extends BaseService {
+  @inject({
+    key: BindingKeys.build({
+      namespace: BindingNamespaces.REPOSITORY,
+      key: UserRepository.name,
+    }),
+  })
+  protected userRepository!: UserRepository;
+
+  constructor(opts: { scope: string }) {
+    super(opts);
+  }
+
+  abstract run(): Promise<void>;
+}
+
+// Concrete subclass takes no constructor parameters - only container-instantiated
+// classes are subject to the "every parameter decorated" rule, and an empty
+// parameter list trivially satisfies it
+export class UserAuditTestService extends BaseTestService {
+  constructor() {
+    super({ scope: UserAuditTestService.name });
+  }
+
+  async run(): Promise<void> {
+    this.logger.for('run').info('Running user audit tests');
+    // ...
+  }
+}
+```
+
+Register the concrete class - never the abstract base:
+
+```typescript
+this.service(UserAuditTestService);
+```
+
+> [!IMPORTANT]
+> `BaseTestService`'s own constructor (`opts: { scope: string }`) is never processed by the container - `BaseTestService` is abstract and is never passed to `instantiate()`. Only the concrete class the container actually instantiates is subject to the "every parameter decorated" rule. See [Dependency Injection Reference](./dependency-injection.md#instantiation-algorithm-two-phase) for the full rule.
+
+---
+
+## Transaction Orchestration
+
+Services are the correct place to manage transactions that span multiple repository calls. Begin a transaction on the DataSource and pass it through repository options:
+
+```typescript
+import { BaseService, BindingKeys, BindingNamespaces, inject } from '@venizia/ignis';
+import { PostgresDataSource } from '../datasources';
+
+export class CheckoutService extends BaseService {
+  constructor(
+    @inject({ key: 'datasources.PostgresDataSource' })
+    private dataSource: PostgresDataSource,
+
+    @inject({ key: 'repositories.OrderRepository' })
+    private orderRepository: OrderRepository,
+
+    @inject({ key: 'repositories.InventoryRepository' })
+    private inventoryRepository: InventoryRepository,
+  ) {
+    super({ scope: CheckoutService.name });
+  }
+
+  async placeOrder(opts: { userId: string; items: OrderItem[] }): Promise<Order> {
+    const log = this.logger.for('placeOrder');
+    const transaction = await this.dataSource.beginTransaction();
+
+    try {
+      const { data: order } = await this.orderRepository.create({
+        data: { userId: opts.userId },
+        options: { transaction },
+      });
+
+      for (const item of opts.items) {
+        await this.inventoryRepository.updateById({
+          id: item.productId,
+          data: { stock: item.quantity },
+          options: { transaction },
+        });
+      }
+
+      await transaction.commit();
+      log.info('Order placed | orderId: %s', order.id);
+      return order;
+    } catch (error) {
+      await transaction.rollback();
+      log.error('Order failed, rolled back | error: %s', error);
+      throw error;
+    }
+  }
+}
+```
+
+Pass `{ transaction }` in the `options` field of any repository call. The repository API is identical with or without a transaction - only the underlying Drizzle connector switches.
+
+---
+
+## Resolving a Service Imperatively
+
+When you need to pull a service out of the container at runtime (rather than through constructor injection), use `this.get<T>`:
+
+```typescript
+// In Application.postConfigure() or a lifecycle hook
+const testService = this.get<RowLockingTestService>({
+  key: BindingKeys.build({
+    namespace: BindingNamespaces.SERVICE,
+    key: RowLockingTestService.name,
+  }),
+});
+
+await testService.run();
+```
+
+This is useful for post-start hooks, one-off tasks that run after the server starts, or when the service is not a constructor dependency.
+
+---
+
+## No Built-in CRUD Service
+
+IGNIS intentionally does not provide a `BaseCrudService`. CRUD operations belong in the Repository layer (`DefaultCRUDRepository`). Services exist for business logic that cannot be expressed as pure data access: cross-cutting validation, multi-repository coordination, transaction management, and workflow orchestration.
+
+---
+
+## Provider vs Service
+
+| Aspect | Service | Provider |
+|--------|---------|----------|
+| **Purpose** | Business logic and orchestration | Factory - produces values or instances |
+| **Base class** | `BaseService` | `BaseProvider<T>` |
+| **Key method** | Business methods | `value(container): T` |
+| **Pattern** | Singleton in DI scope | Factory pattern |
+| **Registration** | `this.service(Ctor)` | `this.bind(...).toProvider(Ctor)` |
+
+See [Providers Reference](./providers.md) for the factory pattern details.
+
+---
+
+## See Also
+
+- **Related References:**
+  - [Controllers](./controllers.md) - HTTP handlers that call services
+  - [Repositories](./repositories/) - Data access layer injected into services
+  - [Providers](./providers.md) - Factory pattern, compare with services
+  - [Dependency Injection](./dependency-injection.md) - Container and injection system
+
+- **Guides:**
+  - [Building Services](/guides/core-concepts/services.md)
+  - [Dependency Injection Guide](/guides/core-concepts/dependency-injection.md)
+
+- **Best Practices:**
+  - [Architectural Patterns](/best-practices/architectural-patterns)
+  - [Testing Guide](/guides/tutorials/testing)

package/{wiki → content}/references/configuration/environment-variables.md

@@ -1,14 +1,14 @@
 # Environment Variables Reference
 
-Complete reference of all environment variables used by Ignis framework.
+Complete reference of all environment variables used by IGNIS framework.
 
 
 ## Overview
 
-Ignis uses the `APP_ENV_` prefix for all framework-specific environment variables. This prevents conflicts with system variables like `PATH`, `HOME`, etc.
+IGNIS uses the `APP_ENV_` prefix for all framework-specific environment variables. This prevents conflicts with system variables like `PATH`, `HOME`, etc.
 
 ```bash
-# ✅ Ignis variables
+# ✅ IGNIS variables
 APP_ENV_POSTGRES_HOST=localhost
 
 # ❌ Might conflict with system
@@ -96,9 +96,9 @@ APP_ENV_APPLICATION_ROLES=api,worker
 |----------|----------|---------|-------------|
 | `APP_ENV_SERVER_HOST` | No | `localhost` | Server bind address |
 | `APP_ENV_SERVER_PORT` | No | `3000` | Server port |
-| `APP_ENV_SERVER_BASE_PATH` | No | `/` | Base path for all routes |
-| `HOST` | No | - | Alternative to `APP_ENV_SERVER_HOST` |
-| `PORT` | No | - | Alternative to `APP_ENV_SERVER_PORT` |
+| `APP_ENV_SERVER_BASE_PATH` | No | - | Base path convention (`EnvironmentKeys` constant; not read by the framework itself) |
+| `HOST` | No | - | Alternative to `APP_ENV_SERVER_HOST` (takes precedence) |
+| `PORT` | No | - | Alternative to `APP_ENV_SERVER_PORT` (takes precedence) |
 
 ### Example
 
@@ -116,11 +116,11 @@ APP_ENV_SERVER_BASE_PATH=/v1/api
 
 ### Priority Order
 
-The server configuration uses this priority:
-1. Explicit config in `appConfigs`
-2. `APP_ENV_SERVER_*` variables
-3. `HOST`/`PORT` variables (for cloud platforms)
-4. Default values
+The server host/port resolution uses this priority (`packages/core/src/base/applications/abstract.ts`):
+1. Explicit config passed to the application constructor
+2. `HOST`/`PORT` variables (for cloud platforms)
+3. `APP_ENV_SERVER_HOST`/`APP_ENV_SERVER_PORT` variables
+4. Default values (`localhost`/`3000`)
 
 
 ## Database Variables (PostgreSQL)
@@ -179,13 +179,15 @@ export class PostgresDataSource extends BaseDataSource {
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `APP_ENV_APPLICATION_SECRET` | **Yes** | - | Secret for encrypting JWT payload |
-| `APP_ENV_JWT_SECRET` | **Yes** | - | Secret for signing JWT tokens |
-| `APP_ENV_JWT_EXPIRES_IN` | No | `86400` | Token expiration in seconds (24h default) |
+| `APP_ENV_APPLICATION_SECRET` | Yes* | - | Secret for encrypting JWT payload |
+| `APP_ENV_JWT_SECRET` | Yes* | - | Secret for signing JWT tokens |
+| `APP_ENV_JWT_EXPIRES_IN` | No | - | Token expiration in seconds (e.g., `86400` = 24h) |
+
+*Required by convention when using the authentication component - see below.
 
 ### Security Requirements
 
-Both `APP_ENV_APPLICATION_SECRET` and `APP_ENV_JWT_SECRET` are **mandatory** when using the authentication component. The application will fail to start if these are missing or empty.
+The `AuthenticateComponent` receives its secrets programmatically via the `jwtOptions` binding (`jwtSecret`, `getTokenExpiresFn`), not by reading these environment variables directly. These `EnvironmentKeys` constants are the conventional way for your application to supply those values. The component throws at startup if `jwtSecret` is missing or left at the placeholder value - so wiring it from an unset environment variable will fail the boot.
 
 ### Generate Strong Secrets
 
@@ -218,6 +220,12 @@ APP_ENV_JWT_EXPIRES_IN=86400
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `APP_ENV_LOGGER_FOLDER_PATH` | No | `./` | Directory for log files |
+| `APP_ENV_LOGGER_FORMAT` | No | `text` | Log output format |
+| `APP_ENV_LOGGER_INSPECT_DEPTH` | No | `5` | How deep a `%s` argument is inspected. Node hard-codes depth `0` for `%s`, which prints `[Object]` one level in; IGNIS widens it. Non-negative integers only - an absent, invalid or negative value falls back to `5` |
+| `APP_ENV_LOGGER_FILE_FREQUENCY` | No | `1h` | Log file rotation frequency |
+| `APP_ENV_LOGGER_FILE_MAX_SIZE` | No | `100m` | Max size per log file |
+| `APP_ENV_LOGGER_FILE_MAX_FILES` | No | `5d` | Log file retention |
+| `APP_ENV_LOGGER_FILE_DATE_PATTERN` | No | `YYYYMMDD_HH` | Rotated file date pattern |
 | `APP_ENV_LOGGER_DGRAM_HOST` | No | - | UDP log transport host |
 | `APP_ENV_LOGGER_DGRAM_PORT` | No | - | UDP log transport port |
 | `APP_ENV_LOGGER_DGRAM_LABEL` | No | - | Label for UDP logs |
@@ -240,6 +248,9 @@ APP_ENV_LOGGER_DGRAM_LEVELS=error,warn,info
 
 ## Storage Variables (MinIO/S3)
 
+> [!NOTE]
+> These are application-level conventions (used by the `vert` reference application), not variables read by the framework. `MinioHelper` and the StaticAsset component receive their configuration programmatically - your application wires these values in.
+
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `APP_ENV_MINIO_HOST` | Yes* | - | MinIO/S3 endpoint |
@@ -248,7 +259,7 @@ APP_ENV_LOGGER_DGRAM_LEVELS=error,warn,info
 | `APP_ENV_MINIO_SECRET_KEY` | Yes* | - | Secret key |
 | `APP_ENV_MINIO_USE_SSL` | No | `false` | Enable SSL |
 
-*Required when using StaticAsset component.
+*Required (by application convention) when wiring MinIO-backed storage.
 
 ### Example
 
@@ -271,17 +282,20 @@ APP_ENV_MINIO_USE_SSL=true
 
 ## Mail Variables
 
+> [!NOTE]
+> These are application-level conventions, not variables read by the framework. The Mail component's transporter receives its SMTP/OAuth2 configuration programmatically - your application wires these values in.
+
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `APP_ENV_MAIL_HOST` | Yes* | `smtp.gmail.com` | SMTP host |
-| `APP_ENV_MAIL_PORT` | No | `465` | SMTP port |
-| `APP_ENV_MAIL_SECURE` | No | `true` | Use TLS |
+| `APP_ENV_MAIL_HOST` | Yes* | - | SMTP host (e.g., `smtp.gmail.com`) |
+| `APP_ENV_MAIL_PORT` | No | - | SMTP port (e.g., `465`) |
+| `APP_ENV_MAIL_SECURE` | No | - | Use TLS |
 | `APP_ENV_MAIL_USER` | Yes* | - | SMTP username/email |
 | `APP_ENV_MAIL_CLIENT_ID` | Yes* | - | OAuth2 client ID |
 | `APP_ENV_MAIL_CLIENT_SECRET` | Yes* | - | OAuth2 client secret |
 | `APP_ENV_MAIL_REFRESH_TOKEN` | Yes* | - | OAuth2 refresh token |
 
-*Required when using Mail component with OAuth2.
+*Required (by application convention) when wiring the Mail component with OAuth2.
 
 ### Example (Gmail with OAuth2)
 
@@ -310,14 +324,16 @@ APP_ENV_MAIL_REFRESH_TOKEN=your-oauth2-refresh-token
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `DEBUG` | No | - | Enable debug mode |
-| `NODE_ENV` | No | `development` | Environment mode |
+| `NODE_ENV` | No | `development` | Environment mode. One of `local`, `debug`, `development`, `dev`, `sit`, `uat`, `alpha`, `beta`, `staging`, `production` |
 | `ALLOW_EMPTY_ENV_VALUE` | No | `false` | Allow empty env values |
 
+The gate is fail-closed: an environment IGNIS does not recognise is treated as production, so error responses are sanitized. `local`, `debug`, `development`, `dev` and `sit` are the development environments - only they expose internal error detail. `alpha`, `beta`, `staging` and `production` stay sanitized.
+
 ### Example
 
 ```bash
-# Development
-NODE_ENV=development
+# Development - `dev` is an alias of `development`, and gets the same error detail
+NODE_ENV=dev
 DEBUG=true
 
 # Production
@@ -347,20 +363,20 @@ project/
 
 ## Custom Environment Prefix
 
-You can customize the prefix from `APP_ENV_` to something else:
+You can customize the prefix from `APP_ENV` to something else via the `APPLICATION_ENV_PREFIX` variable. It is read once when `@venizia/ignis-helpers` loads, so set it in the shell (or before any framework import):
 
-```typescript
-// Set custom prefix
-process.env.APPLICATION_ENV_PREFIX = 'MY_APP';
+```bash
+# Set custom prefix
+APPLICATION_ENV_PREFIX=MY_APP
 
-// Now use MY_APP_ prefix
-// MY_APP_POSTGRES_HOST=localhost
+# Now use MY_APP_ prefix
+MY_APP_POSTGRES_HOST=localhost
 ```
 
 
 ## Validation
 
-Ignis validates `APP_ENV_*` variables on startup. Missing required variables will cause the application to fail with a clear error message.
+On startup, IGNIS iterates every `APP_ENV_*` (prefixed) variable that is set and throws if any has an empty value (`validateEnvs` in `packages/core/src/base/applications/abstract.ts`). It does not check for variables that are absent entirely - component-level validation (e.g., the authentication component's `jwtSecret` check) covers required values.
 
 ### Disable Validation
 

package/{wiki → content}/references/configuration/index.md

@@ -1,6 +1,6 @@
 # Configuration Reference
 
-Configuration options and environment variables for Ignis applications.
+Configuration options and environment variables for IGNIS applications.
 
 ## Quick Reference
 
@@ -11,15 +11,15 @@ Configuration options and environment variables for Ignis applications.
 | Database | PostgreSQL connection | `APP_ENV_POSTGRES_HOST`, `APP_ENV_POSTGRES_DATABASE` |
 | Authentication | JWT tokens and secrets | `APP_ENV_JWT_SECRET`, `APP_ENV_APPLICATION_SECRET` |
 | Logging | Log file paths and transports | `APP_ENV_LOGGER_FOLDER_PATH` |
-| Storage | MinIO/S3 file storage | `APP_ENV_MINIO_HOST`, `APP_ENV_MINIO_ACCESS_KEY` |
-| Mail | SMTP email sending | `APP_ENV_MAIL_HOST`, `APP_ENV_MAIL_USER` |
+| Storage | MinIO/S3 file storage (application-level convention) | `APP_ENV_MINIO_HOST`, `APP_ENV_MINIO_ACCESS_KEY` |
+| Mail | SMTP email sending (application-level convention) | `APP_ENV_MAIL_HOST`, `APP_ENV_MAIL_USER` |
 
 ## Environment Variable Prefix
 
-Ignis uses the `APP_ENV_` prefix to avoid conflicts with system variables:
+IGNIS uses the `APP_ENV_` prefix to avoid conflicts with system variables:
 
 ```bash
-# ✅ Ignis variables
+# ✅ IGNIS variables
 APP_ENV_POSTGRES_HOST=localhost
 
 # ❌ Might conflict with system
@@ -69,7 +69,7 @@ project/
 
 ### 3. Validation on Startup
 
-Ignis validates required variables on startup. Missing values cause clear error messages.
+IGNIS validates every set `APP_ENV_*` variable on startup and fails with a clear error if any is empty (bypass with `ALLOW_EMPTY_ENV_VALUE=true`). Absent variables are not flagged - components validate their own required inputs.
 
 > **Related:** [Environment Variables Reference](./environment-variables.md) | [DataSources Guide](../../guides/core-concepts/persistent/datasources)
 

package/{wiki → content}/references/index.md

@@ -1,6 +1,6 @@
 # API Reference
 
-Complete reference documentation for the Ignis framework. Find detailed API docs, type definitions, and usage examples for every class, component, and utility in the framework.
+Complete reference documentation for the IGNIS framework. Find detailed API docs, type definitions, and usage examples for every class, component, and utility in the framework.
 
 <div class="guide-cards">
 
@@ -63,7 +63,7 @@ Complete reference documentation for the Ignis framework. Find detailed API docs
 <span class="stage-num">3</span>
 <h4>Adding Features</h4>
 </div>
-<p><a href="/ignis/extensions/components/authentication/">Auth</a> → <a href="/ignis/extensions/components/socket-io/">Real-time</a> → <a href="/ignis/extensions/components/mail/">Email</a> → <a href="/ignis/extensions/components/swagger">API Docs</a></p>
+<p><a href="/ignis/extensions/components/authentication/">Auth</a> → <a href="/ignis/extensions/components/socket-io/">Real-time</a> → <a href="/ignis/extensions/components/mail/">Email</a> → <a href="/ignis/extensions/components/api-reference">API Docs</a></p>
 <span class="stage-desc">Pre-built components for common features</span>
 </div>
 
@@ -99,7 +99,7 @@ Complete reference documentation for the Ignis framework. Find detailed API docs
 <span class="stage-num">7</span>
 <h4>Testing & Quality</h4>
 </div>
-<p><a href="/ignis/extensions/helpers/testing/">Unit Testing</a> → <a href="./base/repositories/advanced">Mocking & Stubs</a> → <a href="./quick-reference">Best Practices</a></p>
+<p><a href="./base/repositories/advanced">Mocking & Stubs</a> → <a href="./quick-reference">Best Practices</a></p>
 <span class="stage-desc">Testing strategies, quality assurance, and code review</span>
 </div>
 
@@ -123,18 +123,23 @@ class UserController extends BaseRestController {
 
 **Query with Repository:**
 ```typescript
-const users = await userRepo.find({
-  where: { isActive: true },
-  orderBy: { createdAt: 'desc' },
-  limit: 10,
+const users = await userRepository.find({
+  filter: {
+    where: { isActive: true },
+    order: ['createdAt DESC'],
+    limit: 10,
+  },
 });
 ```
 
 **Schedule a Job:**
 ```typescript
-CronHelper.schedule('0 * * * *', async () => {
-  await cleanupExpiredSessions();
-});
+CronHelper.newInstance({
+  cronTime: '0 * * * *',
+  onTick: async () => {
+    await cleanupExpiredSessions();
+  },
+}).start();
 ```
 
 ## Common Imports
@@ -156,7 +161,7 @@ import {
 // Helpers
 import {
   LoggerFactory,
-  RedisHelper,
+  RedisSingleHelper,
   QueueHelper,
 } from '@venizia/ignis-helpers';
 
@@ -166,7 +171,7 @@ import { Container } from '@venizia/ignis-inversion';
 
 ## See Also
 
-- [Getting Started](/guides/) - New to Ignis? Start here
+- [Getting Started](/guides/) - New to IGNIS? Start here
 - [Core Concepts](/guides/core-concepts/application/) - Deep dive into architecture
 - [Best Practices](/best-practices/) - Production patterns
 - [Changelogs](/changelogs/) - Version history