@venizia/ignis-docs 0.2.0 → 0.2.1-1

package/content/guides/get-started/setup.md

@@ -1,59 +1,51 @@
-# Setup
+# Set Up Your Development Environment
 
-Everything you need to start building with IGNIS. This guide covers installation for macOS, Linux, and Windows (via WSL2).
+Get your machine ready to build with IGNIS: a runtime, a database, and an editor. This guide
+covers macOS, Linux, and Windows through WSL2.
 
 ## Requirements
 
-| Tool | Version | Required | Notes |
-|------|---------|----------|-------|
-| **Bun** | >= 1.3 | Yes | Primary runtime, fastest performance |
-| **Node.js** | >= 18 | Alternative | Use if Bun isn't available |
-| **PostgreSQL** | >= 14 | Yes | Primary database |
-| **VS Code** | Latest | Recommended | Best IDE experience with extensions |
+| Tool | Version | Required | Why |
+|------|---------|----------|-----|
+| **Bun** | >= 1.3 | Yes | Installs packages and runs every build; IGNIS never uses npm, yarn, or pnpm |
+| **PostgreSQL** | >= 14 | Yes | Primary database; the repository system assumes Drizzle + `pg` |
+| **VS Code** | Latest | Optional | Best editor support, through ESLint and Prettier extensions |
 
-## Install Runtime
+> IGNIS apps can also run on Node.js 18+ in production, through `@hono/node-server`. That is a
+> deployment choice, not a setup choice - Bun still installs packages and runs every command in
+> this guide.
 
-### Bun (Recommended)
+## Preconditions
 
-```bash
-# macOS / Linux
-curl -fsSL https://bun.sh/install | bash
-
-# Windows (use WSL2)
-# First install WSL2: wsl --install
-# Then run the curl command above in WSL
+- A terminal with permission to install packages (`sudo` on Linux, admin rights on Windows).
+- On Windows, WSL2 installed (`wsl --install`). Run every command in this guide inside WSL2.
 
-# Verify
-bun --version  # Should be 1.3+
-```
-
-### Node.js (Alternative)
+## Step 1: Install Bun
 
 ```bash
-# macOS (Homebrew)
-brew install node@18
+curl -fsSL https://bun.sh/install | bash
+```
 
-# Ubuntu/Debian
-curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
-sudo apt-get install -y nodejs
+On Windows, run this command inside WSL2.
 
-# Windows
-# Download from https://nodejs.org/
+Reload your shell, then confirm the version:
 
-# Verify
-node --version  # Should be 18+
+```bash
+bun --version   # >= 1.3
 ```
 
-## Install PostgreSQL
+## Step 2: Install PostgreSQL
+
+Install and start the server for your OS.
 
-### macOS
+macOS:
 
 ```bash
 brew install postgresql@14
 brew services start postgresql@14
 ```
 
-### Ubuntu/Debian
+Ubuntu/Debian:
 
 ```bash
 sudo apt-get update
@@ -61,11 +53,11 @@ sudo apt-get install postgresql-14
 sudo service postgresql start
 ```
 
-### Windows
+Windows: download the installer from
+[postgresql.org/download/windows](https://www.postgresql.org/download/windows/), or install
+inside WSL2 with the Ubuntu/Debian commands above.
 
-Download from [postgresql.org/download/windows](https://www.postgresql.org/download/windows/) or use WSL2.
-
-### Create Database
+Then create a database for local development:
 
 ```bash
 # macOS
@@ -73,29 +65,20 @@ psql postgres -c "CREATE DATABASE my_app_db;"
 
 # Linux (Ubuntu/Debian)
 sudo -u postgres psql -c "CREATE DATABASE my_app_db;"
-
-# Verify
-psql my_app_db -c "SELECT 1;"  # Should return 1
 ```
 
-## VS Code Setup (Recommended)
+## Step 3: Configure Your Editor (Optional)
 
-### Extensions
+Install the extensions that match IGNIS' ESLint and Prettier setup:
 
 ```bash
-# Essential
 code --install-extension dbaeumer.vscode-eslint
 code --install-extension esbenp.prettier-vscode
-
-# Recommended
 code --install-extension usernamehw.errorlens
 code --install-extension humao.rest-client
-code --install-extension prisma.prisma  # Works with Drizzle too
 ```
 
-### Settings
-
-Create `.vscode/settings.json`:
+Create `.vscode/settings.json` in your project:
 
 ```json
 {
@@ -107,51 +90,47 @@ Create `.vscode/settings.json`:
 }
 ```
 
-## Verify Setup
+## Verify Your Setup
 
 ```bash
-bun --version      # >= 1.3 (or node --version >= 18)
-psql --version     # >= 14
+bun --version                   # >= 1.3
+psql my_app_db -c "SELECT 1;"   # returns 1
 ```
 
+Both commands must succeed before you continue.
+
 ## Troubleshooting
 
-### Bun not found after install
+### Bun command not found after install
+
+Add Bun to your shell profile, then reload it:
 
 ```bash
-# Add to ~/.bashrc or ~/.zshrc
 export BUN_INSTALL="$HOME/.bun"
 export PATH="$BUN_INSTALL/bin:$PATH"
-
-# Then reload
-source ~/.bashrc  # or ~/.zshrc
+source ~/.bashrc   # or ~/.zshrc
 ```
 
-### PostgreSQL permission denied
+### PostgreSQL: permission denied for database
+
+Run the command as the `postgres` user:
 
 ```bash
-# Linux: Use sudo -u postgres
 sudo -u postgres psql -c "CREATE DATABASE my_app_db;"
-
-# macOS: Check if PostgreSQL is running
-brew services list | grep postgresql
 ```
 
-### PostgreSQL connection refused
+### PostgreSQL: connection refused
+
+Check that the server is running, then start it:
 
 ```bash
-# Check if running
 pg_isready
 
-# Start service
-# macOS
-brew services start postgresql@14
-
-# Linux
-sudo service postgresql start
+brew services start postgresql@14   # macOS
+sudo service postgresql start       # Linux
 ```
 
-## Next Steps
+## See Also
 
-- [5-Minute Quickstart](./5-minute-quickstart.md) - Build your first API
-- [Complete Installation](../tutorials/complete-installation.md) - Full project setup
+- [5-Minute Quickstart](./5-minute-quickstart.md) - build your first API
+- [Complete Installation](../tutorials/complete-installation.md) - full project setup

package/content/guides/migrations/redis-helpers-migration.md

@@ -99,15 +99,16 @@ function useRedis(connection: IRedisHelper) { /* ... */ }
 
 ### instanceof checks and concrete bindings
 
-Use the concrete base class (you cannot `instanceof` an interface):
+Use the `isRedisHelper` brand check (you cannot `instanceof` an interface, and `instanceof` against
+the base class answers `false` for a helper built by a second installed copy of the package):
 
 ```typescript
 // Before
 if (connection instanceof DefaultRedisHelper) { /* ... */ }
 
 // After
-import { AbstractRedisHelper } from '@venizia/ignis-helpers';
-if (connection instanceof AbstractRedisHelper) { /* ... */ }
+import { isRedisHelper } from '@venizia/ignis-helpers';
+if (isRedisHelper(connection)) { /* ... */ }
 ```
 
 ### Options type rename
@@ -155,7 +156,7 @@ If you wrapped `subscribe(...)` in a `try/catch` expecting it to throw, that bra
 
 These are new and do not break anything:
 
-- **`RedisSentinelHelper`** - Redis Sentinel topology with automatic failover. See the [Redis Helper reference](/extensions/helpers/redis/) (Sentinel section).
+- **`RedisSentinelHelper`** - Redis Sentinel topology with automatic failover. See the [Redis Helper full reference](/extensions/helpers/redis/reference#construction-sentinel) (Sentinel section).
 - **`createRedisHelper({ mode })`** - a factory that builds the right helper from `RedisModes.SINGLE | CLUSTER | SENTINEL`, so you can pick a topology from config.
 - **`RedisModes`** and **`RedisSentinelRoles`** - const-classes for the enumerable mode/role strings, with matching `TRedisMode` / `TRedisSentinelRole` types.
 - **Expanded data API** - key lifecycle and counters (`exists`, `expire`, `expireAt`, `ttl`, `persist`, `incr`, `decr`, `incrBy`, `decrBy`), hash completion (`hGet`, `hDel`, `hExists`, `hKeys`, `hVals`, `hIncrBy`, `hLen`), sets (`sAdd`, `sRem`, `sMembers`, `sIsMember`, `sCard`), and lists (`lPush`, `rPush`, `lPop`, `rPop`, `lRange`, `lLen`).

package/content/guides/migrations/scoped-rbac-migration.md

@@ -47,18 +47,18 @@ Both are described below with exact before/after.
 
 When you bump ignis, these stop compiling/working:
 
-1. **`packages/core/src/security/application-casbin-adapter.ts`**
+1. **`packages/core-server/src/security/application-casbin-adapter.ts`**
    - `extends DrizzleCasbinAdapter` → class removed.
    - `import { DrizzleCasbinAdapter, IDrizzleCasbinAdapterOptions, ICasbinPolicyFilter } from '@venizia/ignis'` → first two removed; `ICasbinPolicyFilter` still exists but its **shape changed**.
    - `filter.principalValue` / `filter.principalType` → now `filter.principal.id` / `filter.principal.type`.
    - `CasbinRuleVariants.GROUP` / `CasbinRuleVariants.POLICY` → removed.
    - `this.entities.role.principalType` / `this.entities.permission.principalType` → `entities` no longer provided by the base.
 
-2. **`packages/core/src/repositories/public/policy-definition.repository.ts`**
+2. **`packages/core-server/src/repositories/public/policy-definition.repository.ts`**
    - Many `eq(pd.variant, CasbinRuleVariants.GROUP)` / `.POLICY` → constant removed. This file is the
      biggest single breakage surface outside the adapter.
 
-3. **`packages/core/src/application/verifier.ts`** (enforcer registration)
+3. **`packages/core-server/src/application/verifier.ts`** (enforcer registration)
    - The Redis-absent fallback uses `CasbinEnforcerCachedDrivers.IN_MEMORY` → removed. You must pick
      Redis or `{ use: false }`.
 
@@ -78,7 +78,7 @@ your `group`/`policy` variant values, and all bespoke logic (global roles, HQ-ow
 Own these strings locally so you are decoupled from ignis's casbin-prefix enum:
 
 ```ts
-// packages/core/src/security/policy-variant.ts
+// packages/core-server/src/security/policy-variant.ts
 export class PolicyDefinitionVariant {
   /** user→role assignment + user→merchant membership rows. */
   static readonly GROUP = 'group';
@@ -292,7 +292,7 @@ the bespoke adapter and gain resource/action/domain hierarchies for free.
 
 ## 7. Reference - current nx-seller wiring (before)
 
-For context, the current registration (`packages/core/src/application/verifier.ts`) uses:
+For context, the current registration (`packages/core-server/src/application/verifier.ts`) uses:
 `ApplicationCasbinAdapter` (subclass of removed `DrizzleCasbinAdapter`), `CASBIN_RBAC_MODEL` (flat
 `g + p`, exact `r.obj == p.obj`), a Redis-or-in-memory `cached`, `domainMatching { roleDefinition: 'g',
 fn: keyMatch }`, and a `normalizePayloadFn` mapping subject/domain via

package/content/guides/migrations/unified-connectors-migration.md

@@ -7,7 +7,7 @@ description: What changed in @venizia/ignis 0.0.11-0 / @venizia/ignis-helpers 0.
 
 **Target audience:** the BANA (nx-seller) team, and any application upgrading from `@venizia/ignis@0.0.10-x` / `@venizia/ignis-helpers@0.0.9-x`.
 
-**Verification status:** every step below was validated against a full copy of BANA's `packages/core` source compiled against the release tarballs - the migration ends at **zero compile errors**. The search branch was additionally validated end to end against a live 3-node Typesense cluster.
+**Verification status:** every step below was validated against a full copy of BANA's `packages/core-server` source compiled against the release tarballs. The migration ends at **zero compile errors**. The search branch was additionally validated end to end against a live 3-node Typesense cluster.
 
 ## What changed (summary)
 
@@ -15,8 +15,9 @@ IGNIS core was restructured around ONE engine-neutral repository family:
 
 - `src/base` now holds a single `AbstractRepository` / `AbstractDataSource` / `AbstractEntity` family. Every engine implements it under `src/connectors/{postgres,typesense}`.
 - Postgres remains re-exported from the root barrel - **your imports keep working unchanged**. Every connector is also addressable explicitly: `@venizia/ignis/postgres`, `@venizia/ignis/typesense` (typesense is subpath-only; its client is an optional peer).
-- Canonical class names are the paradigm-family names (`BaseRelationalDataSource`, `BaseRelationalEntity`, `DefaultRelationalRepository`, ...); the engine name appears only at the concrete datasource (`TypesenseDataSource`) and the query dialect (`PostgresQueryOperators`). The historical names (`BaseDataSource`, `BaseEntity`, `BasePostgresDataSource`, `BasePostgresEntity`, `RDBQueryOperators`, `DefaultCRUDRepository`, ...) all remain as alias re-exports of the SAME classes - `instanceof`, metadata, and bindings are unaffected. No action required; prefer the family names in new code.
-- New capabilities model: `dataSource.getCapabilities()` and a standardized NotSupported error (HTTP 501, messageCode `core.not_supported`) for engine gaps (e.g. transactions on search engines).
+- Canonical class names are the paradigm-family names (`BaseRelationalDataSource`, `BaseRelationalEntity`, `DefaultRelationalRepository`, ...). The engine name appears only at the concrete datasource (`TypesenseDataSource`) and the query dialect (`PostgresQueryOperators`).
+- The historical names (`BaseDataSource`, `BaseEntity`, `BasePostgresDataSource`, `BasePostgresEntity`, `RDBQueryOperators`, `DefaultCRUDRepository`, ...) all keep resolving from the same import paths. Most are alias re-exports of the SAME classes; the five repository names (`PostgresBaseRepository`, `ReadableRepository`, `PersistableRepository`, `DefaultCRUDRepository`, `SoftDeletableRepository`) are Postgres subclasses of the neutral chain, so they are distinct class objects from their neutral parents. `instanceof`, metadata, and bindings are unaffected. No action required.
+- New capabilities model: `dataSource.getCapabilities()` and a standardized NotSupported error (HTTP 501, `normalized.code` `core.not_supported`) for engine gaps (e.g. transactions on search engines).
 - New engine: the **Typesense search branch** (`BaseSearchEntity`, `defineSearchCollection`, typed `TSearchDocument`, `DefaultSearchRepository`). It does not affect existing postgres code.
 
 ## Required migrations (in order)
@@ -38,7 +39,7 @@ grep -rl 'ITransaction\|IExtraOptions' packages/*/src --include='*.ts' \
   | xargs sed -i 's/\bITransaction\b/IDatabaseTransaction/g; s/\bIExtraOptions\b/IDatabaseExtraOptions/g'
 ```
 
-Note: `options?.transaction?.connector` inside `DefaultCRUDRepository` (alias of `DefaultRelationalRepository`) subclasses needs NO change - the postgres tiers now default their options generic to `IDatabaseExtraOptions`, so that path stays typed automatically.
+Note: `options?.transaction?.connector` inside `DefaultCRUDRepository` (alias of `DefaultRelationalRepository`) subclasses needs NO change. The postgres tiers now default their options generic to `IDatabaseExtraOptions`, so that path stays typed automatically.
 
 ### 2. `applicationEnvironment.get` - options object
 
@@ -68,7 +69,7 @@ New helpers: `toDelimitedArray(input, separator?)` (split + trim + drop empties)
 
 ### 3. Purge stale TypeScript build info
 
-The package's `exports` map changed; stale incremental caches replay phantom diagnostics for unchanged files (a page of bogus "missing property" errors while new files compile clean):
+The package's `exports` map changed. Stale incremental caches replay phantom diagnostics for unchanged files - a page of bogus "missing property" errors while new files compile clean:
 
 ```bash
 find . -name '*.tsbuildinfo' -not -path '*/node_modules/*' -delete
@@ -78,7 +79,7 @@ Run this once after the version bump, before trusting the first `tsc` run.
 
 ### 4. Auth endpoint error contract (only if you assert on it)
 
-The three auth endpoints backed by unimplemented service methods (`refreshToken`, `getUserInformation`) now return the standardized NotSupported error: HTTP 501 with messageCode `core.not_supported` and message `[AuthController] <feature> is not supported.` (previously a plain `Method not implemented`). BANA was scanned: no code asserts on the old string - listed for completeness.
+The three auth endpoints backed by unimplemented service methods (`refreshToken`, `getUserInformation`) now return the standardized NotSupported error: HTTP 501 with `normalized.code` `core.not_supported` and message `[AuthController] <feature> is not supported.`. Previously this was a plain `Method not implemented`. BANA was scanned: no code asserts on the old string - listed for completeness.
 
 ## Strongly recommended (not compile-blocking)
 
@@ -109,5 +110,5 @@ All IGNIS examples now declare these explicitly.
 
 - No import-path changes: root-barrel imports of `BaseDataSource`, `BaseEntity`, `DefaultCRUDRepository`, decorators, etc. all keep working (dual-door export model + compatibility aliases).
 - No repository/generic signature changes: `DefaultCRUDRepository<Schema, DataObject, PersistObject, ...>` call sites are unchanged (a 4th options generic was APPENDED with a default).
-- No runtime behavior changes on the postgres path: the whole pre-existing RDB behavior suite runs unchanged inside the release gates, and every behavior delta was verified to have no trigger inside BANA (`@model` tableName divergence: 0 occurrences; message-string assertions: 0).
+- No runtime behavior changes on the postgres path: the whole pre-existing RDB behavior suite runs unchanged inside the release gates. Every behavior delta was verified to have no trigger inside BANA (`@model` tableName divergence: 0 occurrences; message-string assertions: 0).
 - Nothing search-related: BANA imports zero search symbols today.

package/content/guides/tutorials/ecommerce-api.md

@@ -526,12 +526,11 @@ export class OrderRepository extends DefaultCRUDRepository<typeof Order.schema>
 
 ```typescript
 // src/services/product.service.ts
-import { injectable, inject } from '@venizia/ignis';
+import { inject } from '@venizia/ignis';
 import { BaseService } from '@venizia/ignis';
 import { ProductRepository } from '../repositories/product.repository';
 import { getError } from '@venizia/ignis-helpers';
 
-@injectable({})
 export class ProductService extends BaseService {
   constructor(
     @inject({ key: 'repositories.ProductRepository' })
@@ -595,7 +594,7 @@ export class ProductService extends BaseService {
 
 ```typescript
 // src/services/cart.service.ts
-import { injectable, inject } from '@venizia/ignis';
+import { inject } from '@venizia/ignis';
 import { BaseService } from '@venizia/ignis';
 import { CartRepository } from '../repositories/cart.repository';
 import { ProductService } from './product.service';
@@ -606,7 +605,6 @@ interface ICartItem {
   quantity: number;
 }
 
-@injectable({})
 export class CartService extends BaseService {
   constructor(
     @inject({ key: 'repositories.CartRepository' })
@@ -733,7 +731,7 @@ export class CartService extends BaseService {
 
 ```typescript
 // src/services/order.service.ts
-import { injectable, inject } from '@venizia/ignis';
+import { inject } from '@venizia/ignis';
 import { BaseService } from '@venizia/ignis';
 import { OrderRepository } from '../repositories/order.repository';
 import { CartService } from './cart.service';
@@ -758,7 +756,6 @@ interface ICreateOrderInput {
   billingAddress?: IOrderAddress;
 }
 
-@injectable({})
 export class OrderService extends BaseService {
   constructor(
     @inject({ key: 'repositories.OrderRepository' })
@@ -906,12 +903,10 @@ export class OrderService extends BaseService {
 
 ```typescript
 // src/services/payment.service.ts
-import { injectable } from '@venizia/ignis';
 import { BaseService } from '@venizia/ignis';
 import Stripe from 'stripe';
 import { applicationEnvironment } from '@venizia/ignis-helpers';
 
-@injectable({})
 export class PaymentService extends BaseService {
   private _stripe: Stripe;
 

package/content/guides/tutorials/realtime-chat.md

@@ -973,7 +973,7 @@ export class ChatService extends BaseService {
 ```
 
 > [!IMPORTANT]
-> **Lazy getter pattern**: `SocketIOServerHelper` is bound via a post-start hook, so it's not available during DI construction. The `private get socketIOHelper()` getter resolves it lazily on first access. See [Socket.IO Component](/extensions/components/socket-io/#step-3-use-in-servicescontrollers) for details.
+> **Lazy getter pattern**: `SocketIOServerHelper` is bound via a post-start hook, so it's not available during DI construction. The `private get socketIOHelper()` getter resolves it lazily on first access. See [Send a message from a service](/extensions/components/socket-io/#send-a-message-from-a-service) for details.
 
 ## 6. Application Setup
 

package/content/references/base/application.md

@@ -1,35 +1,40 @@
 ---
 title: Application Reference
-description: Technical reference for AbstractApplication and BaseApplication classes
+description: Technical reference for the four application layers - AbstractApplication, RestApplication, ServerApplication and BaseApplication
 difficulty: beginner
 ---
 
 # Deep Dive: Application
 
-Technical reference for `AbstractApplication` and `BaseApplication` - the foundation classes for every IGNIS application.
+Extend `BaseApplication`. The three classes above it exist so a host that cannot open a socket - a browser Worker, a test harness - can still serve the same controllers.
 
 **Files:**
-- `packages/core/src/base/applications/abstract.ts`
-- `packages/core/src/base/applications/base.ts`
-- `packages/core/src/base/applications/types.ts`
+- `packages/kernel/src/base/applications/abstract.ts`
+- `packages/kernel/src/base/applications/rest.ts`
+- `packages/core-server/src/base/applications/server.ts`
+- `packages/core-server/src/base/applications/base.ts`
+- `packages/kernel/src/base/applications/types.ts`
 
 ## Quick Reference
 
-| Class | Purpose | Key Methods |
-|-------|---------|-------------|
-| **AbstractApplication** | Base class with lifecycle management, server start/stop | `start()`, `stop()`, `init()`, `validateEnvs()` |
-| **BaseApplication** | Concrete implementation with resource registration and boot support | `component()`, `controller()`, `service()`, `repository()`, `dataSource()`, `boot()` |
+Each layer adds one capability. The first two ship from `@venizia/ignis-kernel` and touch no node builtin; the last two ship from `@venizia/ignis`.
+
+| Class | Adds | Key Methods |
+|-------|------|-------------|
+| **AbstractApplication** | config, lifecycle hooks, the DI container | `init()`, `registerPostStartHook()`, `registerPostStopHook()` |
+| **RestApplication** | the two `OpenAPIHono` routers | `getServer()`, `getRootRouter()`, `inspectRoutes()` |
+| **ServerApplication** | the socket | `start()`, `stop()`, `getServerHost()`, `getServerPort()`, `getServerAddress()` |
+| **BaseApplication** | resource registration, secrets, boot | `component()`, `controller()`, `service()`, `repository()`, `dataSource()`, `boot()`, `validateEnvs()` |
+
+> [!NOTE]
+> Every symbol still resolves from `@venizia/ignis` - `packages/core-server` re-exports the kernel wholesale. The split changed no import path.
 
 ## `AbstractApplication`
 
-Base class responsible for core lifecycle and server management. Extends `Container` (IoC container) and implements `IApplication`.
+Config, lifecycle and the container. No router, no server. Extends `Container`.
 
 ```typescript
-abstract class AbstractApplication<
-  AppEnv extends Env = Env,
-  AppSchema extends Schema = {},
-  BasePath extends string = '/',
-> extends Container implements IApplication<AppEnv, AppSchema, BasePath>
+abstract class AbstractApplication extends Container
 ```
 
 ### Constructor
@@ -39,10 +44,47 @@ constructor(opts: { scope: string; config: IApplicationConfigs })
 ```
 
 The constructor:
-1. Merges the provided config with defaults (host from `HOST` or `APP_ENV_SERVER_HOST` env, port from `PORT` or `APP_ENV_SERVER_PORT` env, defaults to `localhost:3000`)
-2. Enables `asyncContext` by default (`{ enable: true }`)
-3. Sets `strictPath` to `true` by default for the Hono instance
-4. Creates two `OpenAPIHono` instances: the main server and a `rootRouter`
+1. Merges the provided config with defaults, taking host and port from `getEnvServerHost()` / `getEnvServerPort()` and falling back to `localhost:3000`
+2. Resolves `asyncContext.enable` from `getDefaultAsyncContextEnabled()`
+3. Sets `projectRoot` from `getProjectRoot()`
+
+Port `0` survives that merge on purpose - it asks the operating system for an ephemeral port.
+
+The constructor binds nothing. `registerCoreBindings()` runs from `init()`, and `init()` is not called for you - see [Lifecycle](#lifecycle) below.
+
+### The four constructor hooks
+
+`getEnvServerHost()`, `getEnvServerPort()`, `getDefaultAsyncContextEnabled()` and `getProjectRoot()` return `undefined`, `undefined`, `false` and `''` here. `ServerApplication` overrides all four to restore server behaviour - `process.env.HOST`, `process.env.PORT`, `true`, and `process.cwd()`. The kernel layers read no `process`, because a browser Worker has none.
+
+> [!WARNING]
+> All four run inside this constructor, before any subclass field is assigned. An override must return a literal or read module-level state only. Reading `this.something` from one yields `undefined`, silently. `getProjectRoot()` is the one applications most often override - keep it free of instance state.
+
+## `RestApplication`
+
+Adds the routers, and nothing that opens a socket.
+
+```typescript
+abstract class RestApplication<
+  AppEnv extends Env = Env,
+  AppSchema extends Schema = {},
+  BasePath extends string = '/',
+> extends AbstractApplication
+```
+
+It builds the two `OpenAPIHono` instances - the main server and the `rootRouter` - and binds them as `APPLICATION_SERVER` and `APPLICATION_ROOT_ROUTER`.
+
+## `ServerApplication`
+
+Adds `start()`, `stop()` and the runtime detection that picks `Bun.serve` or `@hono/node-server`.
+
+```typescript
+abstract class ServerApplication<
+  AppEnv extends Env = Env,
+  AppSchema extends Schema = {},
+  BasePath extends string = '/',
+> extends RestApplication<AppEnv, AppSchema, BasePath>
+  implements IApplication<AppEnv, AppSchema, BasePath>
+```
 5. Auto-detects the runtime (Bun or Node.js)
 
 ### Key Features
@@ -120,11 +162,11 @@ protected server:
 
 ## `BaseApplication`
 
-Extends `AbstractApplication` with concrete lifecycle implementations, resource registration, and boot support. Implements `IRestApplication` and `IBootableApplication`.
+Extends `ServerApplication` with concrete lifecycle implementations, resource registration, secrets hydration and boot support. Implements `IRestApplication` and `IBootableApplication`. This is the class your application extends.
 
 ```typescript
 abstract class BaseApplication
-  extends AbstractApplication
+  extends ServerApplication
   implements IRestApplication, IBootableApplication
 ```
 
@@ -266,7 +308,7 @@ graph TD
 
 Automatically registers these default middlewares during `initialize()`:
 
-1. **Error handler** (`appErrorHandler`) - with optional `rootKey` from `configs.error.rootKey`
+1. **Error handler** (`AppErrorMiddleware`) - with optional `rootKey` from `configs.error.rootKey`
 2. **Async context storage** (`contextStorage`) - enabled by default via `configs.asyncContext.enable`
 3. **Not-found handler** (`notFoundHandler`)
 4. **RequestTrackerComponent** - assigns `x-request-id` to every request, includes request body parsing

package/content/references/base/components.md

@@ -8,7 +8,7 @@ difficulty: advanced
 
 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`
+**File:** `packages/core-server/src/base/components/base.ts`
 
 ## Quick Reference
 
@@ -379,7 +379,7 @@ If gRPC controllers are discovered but the `'grpc'` transport is not in the `tra
 
 ### `RestComponent`
 
-**File:** `packages/core/src/components/controller/rest/rest.component.ts`
+**File:** `packages/core-server/src/components/controller/rest/rest.component.ts`
 
 Discovers all controller bindings tagged with `BindingNamespaces.CONTROLLER`, skips any whose metadata has `transport === ControllerTransports.GRPC`, and configures the rest as REST controllers.
 
@@ -422,7 +422,7 @@ export class RestBindingKeys {
 
 ### `GrpcComponent`
 
-**File:** `packages/core/src/components/controller/grpc/grpc.component.ts`
+**File:** `packages/core-server/src/components/controller/grpc/grpc.component.ts`
 
 Discovers all controller bindings tagged with `BindingNamespaces.CONTROLLER`, skips any whose metadata does **not** have `transport === ControllerTransports.GRPC`, and configures gRPC controllers.