@venizia/ignis-docs 0.0.5 → 0.0.6-0

package/wiki/references/components/swagger.md

@@ -1,138 +1,68 @@
-# Swagger/OpenAPI Component
+# Swagger/OpenAPI
 
-Automatic interactive API documentation generation using OpenAPI specifications.
+Automatic interactive API documentation generation using OpenAPI specifications, powered by Scalar or Swagger UI.
 
 ## Quick Reference
 
-| Component | Purpose |
-|-----------|---------|
-| **SwaggerComponent** | Configures documentation UI and routes |
-| **UIProviderFactory** | Manages UI providers (Swagger UI, Scalar) |
-| **Default UI** | Scalar (can be changed to Swagger UI) |
-
-### Default Endpoints
-
-| Path | Description |
-|------|-------------|
-| `/doc/explorer` | Documentation UI (Scalar by default) |
-| `/doc/openapi.json` | Raw OpenAPI specification |
-
-### UI Provider Types
+| Item | Value |
+|------|-------|
+| **Package** | `@venizia/ignis` |
+| **Class** | `SwaggerComponent` |
+| **UI Factory** | `UIProviderFactory` |
+| **Runtimes** | Both |
 
 | Provider | Value | When to Use |
 |----------|-------|-------------|
 | **Scalar** | `'scalar'` | Modern, clean UI (default) |
 | **Swagger UI** | `'swagger'` | Classic Swagger interface |
 
-## Architecture Components
-
--   **`SwaggerComponent`**: Configures documentation UI and registers routes
--   **`UIProviderFactory`**: Manages different UI providers
--   **`@hono/zod-openapi`**: Powers OpenAPI generation from Zod schemas
--   **Integration**: Works with controller `defineRoute` methods using Zod schemas
-
-## Implementation Details
-
-### Tech Stack
-
--   **Hono**
--   **`@hono/zod-openapi`**
--   **`@hono/swagger-ui`** (for Swagger UI)
--   **`@scalar/hono-api-reference`** (for Scalar UI)
--   **`zod`**
-
-### Configuration
-
-The Swagger component can be configured via the `ISwaggerOptions` binding. You can customize the documentation path, OpenAPI version, and the UI provider type.
-
-**`ISwaggerOptions` Interface:**
-
+#### Import Paths
 ```typescript
-export interface ISwaggerOptions {
-  restOptions: {
-    base: { path: string }; // Base path for all documentation routes
-    doc: { path: string };  // Path to the raw openapi.json file
-    ui: {
-      path: string;         // Path to the documentation UI
-      type: 'swagger' | 'scalar'; // Type of UI to render
-    };
-  };
-  explorer: {
-    openapi: string;
-    info?: { /* ... */ };
-    servers?: Array<{ url: string; description?: string; }>;
-  };
-  uiConfig?: Record<string, any>; // Custom config for the UI provider
-}
+import { SwaggerComponent, SwaggerBindingKeys, UIProviderFactory } from '@venizia/ignis';
+import type { ISwaggerOptions, IUIProvider, IUIConfig, IGetProviderParams } from '@venizia/ignis';
 ```
 
-**Default Options:**
+## Setup
+
+### Step 1: Bind Configuration (Optional)
 
-The default UI provider is `scalar`.
+Skip this step to use the defaults (Scalar UI at `/doc/explorer`). To customize:
 
 ```typescript
-const DEFAULT_SWAGGER_OPTIONS: ISwaggerOptions = {
+// In your Application class's preConfigure method (src/application.ts)
+import { SwaggerBindingKeys, ISwaggerOptions } from '@venizia/ignis';
+
+this.bind<ISwaggerOptions>({
+  key: SwaggerBindingKeys.SWAGGER_OPTIONS,
+}).toValue({
   restOptions: {
     base: { path: '/doc' },
     doc: { path: '/openapi.json' },
-    ui: { path: '/explorer', type: 'scalar' },
+    ui: { path: '/explorer', type: 'swagger' }, // Use Swagger UI instead of Scalar
   },
-  // ...
-};
+  explorer: {
+    openapi: '3.0.0',
+  },
+});
 ```
 
-### Code Samples
-
-#### 1. Registering the Swagger Component
-
-In your `src/application.ts`, register the `SwaggerComponent`.
+### Step 2: Register Component
 
 ```typescript
 // src/application.ts
 import { SwaggerComponent, BaseApplication, ValueOrPromise } from '@venizia/ignis';
 
 export class Application extends BaseApplication {
-    // ...
-    preConfigure(): ValueOrPromise<void> {
-        // ...
-        this.component(SwaggerComponent);
-        // ...
-    }
-    // ...
-}
-```
-
-#### 2. Customizing the UI Provider
-
-To change the UI provider to Swagger UI, you can bind custom options in your application's `preConfigure` method.
-
-```typescript
-import { SwaggerComponent, SwaggerBindingKeys, ISwaggerOptions } from '@venizia/ignis';
-
-// ... in your Application class's preConfigure method
   preConfigure(): ValueOrPromise<void> {
     // ...
-    this.bind<ISwaggerOptions>({
-      key: SwaggerBindingKeys.SWAGGER_OPTIONS,
-    }).toValue({
-      restOptions: {
-        base: { path: '/doc' },
-        doc: { path: '/openapi.json' },
-        ui: { path: '/explorer', type: 'swagger' }, // Use Swagger UI
-      },
-      explorer: {
-        openapi: '3.0.0',
-      },
-    });
-
     this.component(SwaggerComponent);
-    // ...
   }
+}
 ```
 
-#### 3. Defining Routes with Zod Schemas
+### Step 3: Define Routes with Zod Schemas
 
-To get the most out of the documentation, define your routes with `zod` schemas.
+To get the most out of the documentation, define your routes with `zod` schemas:
 
 ```typescript
 // src/controllers/hello.controller.ts
@@ -165,28 +95,378 @@ export class HelloController extends BaseController {
 }
 ```
 
-## API or Interface Specifications
+> [!TIP]
+> Controllers using `defineRoute` with Zod schemas automatically generate OpenAPI specs. The Swagger component discovers all registered controller routes and renders them in the documentation UI.
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `restOptions.base.path` | `string` | `'/doc'` | Base path for all documentation routes |
+| `restOptions.doc.path` | `string` | `'/openapi.json'` | Path to the raw OpenAPI spec (relative to base) |
+| `restOptions.ui.path` | `string` | `'/explorer'` | Path to the documentation UI (relative to base) |
+| `restOptions.ui.type` | `'swagger' \| 'scalar'` | `'scalar'` | UI provider type |
+| `explorer.openapi` | `string` | `'3.0.0'` | OpenAPI specification version |
+| `uiConfig` | `Record<string, any>` | `undefined` | Custom config passed to the UI provider |
+
+> [!IMPORTANT]
+> The `explorer.info` field is **always overwritten** during the component's `binding()` phase. The component unconditionally reads your application's `package.json` via `application.getAppInfo()` and sets `explorer.info` to `{ title, version, description, contact }` from that data. Any user-provided `explorer.info` values are discarded. If you need to customize these fields, update your `package.json` instead.
+
+> [!NOTE]
+> The `explorer.servers` field is auto-populated only when empty. If you provide `explorer.servers` with at least one entry, the component preserves your values. When no servers are configured, it creates a default entry from `application.getServerAddress()` plus the application base path.
+
+#### ISwaggerOptions -- Full Reference
+```typescript
+export interface ISwaggerOptions {
+  restOptions: {
+    base: { path: string };
+    doc: { path: string };
+    ui: { path: string; type: TDocumentUIType };
+  };
+  explorer: {
+    openapi: string;
+    info?: {
+      title: string;
+      version: string;
+      description: string;
+      contact?: { name: string; email: string };
+    };
+    servers?: Array<{
+      url: string;
+      description?: string;
+    }>;
+  };
+  uiConfig?: Record<string, any>;
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `restOptions.base.path` | `string` | `'/doc'` | Base path for all documentation routes |
+| `restOptions.doc.path` | `string` | `'/openapi.json'` | Path to the raw OpenAPI spec (relative to base) |
+| `restOptions.ui.path` | `string` | `'/explorer'` | Path to the documentation UI (relative to base) |
+| `restOptions.ui.type` | `'swagger' \| 'scalar'` | `'scalar'` | UI provider type |
+| `explorer.openapi` | `string` | `'3.0.0'` | OpenAPI specification version |
+| `explorer.info.title` | `string` | Always from `package.json` `name` | API title (overwritten at runtime) |
+| `explorer.info.version` | `string` | Always from `package.json` `version` | API version (overwritten at runtime) |
+| `explorer.info.description` | `string` | Always from `package.json` `description` | API description (overwritten at runtime) |
+| `explorer.info.contact` | `{ name, email }` | Always from `package.json` `author` | Contact information (overwritten at runtime) |
+| `explorer.servers` | `Array<{ url, description? }>` | Auto-detected when empty | Server URLs |
+| `uiConfig` | `Record<string, any>` | `undefined` | Custom config passed to the UI provider |
+
+#### IGetProviderParams Interface
+
+The `IGetProviderParams` interface is used by `UIProviderFactory.getProvider()` and `UIProviderFactory.register()`:
+
+```typescript
+export interface IGetProviderParams {
+  type: string;
+}
+```
+
+This interface is exported for use when building custom tooling around the `UIProviderFactory` -- for example, programmatically querying which providers are available or registering providers in tests.
+
+### Tech Stack
+
+| Library | Purpose |
+|---------|---------|
+| `@hono/zod-openapi` | OpenAPI generation from Zod schemas |
+| `@hono/swagger-ui` | Swagger UI rendering |
+| `@scalar/hono-api-reference` | Scalar UI rendering |
+| `zod` | Schema validation and type generation |
+
+> [!TIP]
+> The component also auto-registers JWT (`bearer`) and Basic security schemes in the OpenAPI spec, so authenticated endpoints display the correct auth UI in the documentation.
+
+## Architecture
+
+### Component Lifecycle
+
+The `SwaggerComponent` executes the following during `binding()`:
+
+1. **Resolve options** -- reads `SwaggerBindingKeys.SWAGGER_OPTIONS` from DI using `application.get()` with `isOptional: true`, falls back to `DEFAULT_SWAGGER_OPTIONS` via the `??` operator if no binding exists
+2. **Overwrite info** -- unconditionally reads `package.json` via `application.getAppInfo()` and overwrites `explorer.info` with `{ title: appInfo.name, version: appInfo.version, description: appInfo.description, contact: appInfo.author }`
+3. **Auto-detect servers** -- if `explorer.servers` is empty or unset, creates one entry from `http://` + `application.getServerAddress()` + `configs.path.base`
+4. **Normalize paths** -- all path segments (`base.path`, `doc.path`, `ui.path`) are normalized to ensure a leading `/` is present, handling both `/path` and `path` inputs
+5. **Register OpenAPI doc route** -- calls `rootRouter.doc(docPath, explorer)` to register the raw JSON endpoint
+6. **Resolve UI type with fallback** -- evaluates `restOptions.ui.type || DocumentUITypes.SWAGGER`. Note: this means a falsy value (empty string) falls back to `'swagger'`, not `'scalar'`
+7. **Validate UI type** -- checks the resolved type against `DocumentUITypes.SCHEME_SET`, throws if invalid
+8. **Register UI provider** -- calls `UIProviderFactory.register({ type })` to instantiate the UI renderer
+9. **Construct docUrl** -- builds the full documentation URL by joining `configs.path.base`, `configs.basePath`, and the computed `docPath`
+10. **Register UI route** -- creates `GET` handler at `uiPath` that calls `uiProvider.render()` with `{ title: appInfo.name, url: docUrl, ...uiConfig }`
+11. **Register security schemes** -- auto-registers JWT (bearer) and Basic security schemes in the OpenAPI registry
+
+### Architecture Components
+
+| Component | Class | Role |
+|-----------|-------|------|
+| **SwaggerComponent** | `extends BaseComponent` | Orchestrates binding, overwrites OpenAPI metadata from `package.json` |
+| **UIProviderFactory** | `extends MemoryStorageHelper` (singleton) | Registry for UI providers, validates and instantiates |
+| **SwaggerUIProvider** | `implements IUIProvider` | Renders Swagger UI via `@hono/swagger-ui` |
+| **ScalarUIProvider** | `implements IUIProvider` | Renders Scalar UI via `@scalar/hono-api-reference` |
+
+#### UIProviderFactory and MemoryStorageHelper
+
+`UIProviderFactory` extends `MemoryStorageHelper<{ [key: string | symbol]: IUIProvider }>`, which provides a simple in-memory key-value store with the following methods used internally:
+
+- `isBound(key)` -- checks if a provider type is already registered
+- `get(key)` -- retrieves a registered provider instance
+- `set(key, value)` -- stores a provider instance
+- `keys()` -- lists all registered provider type keys
+
+This gives the factory a lightweight, type-safe storage backend without requiring the full DI container.
+
+#### Lazy Dynamic Imports
+
+Both `SwaggerUIProvider` and `ScalarUIProvider` use `await import()` inside their `render()` method to load the underlying UI library:
+
+```typescript
+// SwaggerUIProvider
+async render(context, config, next) {
+  const { swaggerUI } = await import('@hono/swagger-ui');
+  // ...
+}
+
+// ScalarUIProvider
+async render(context, config, next) {
+  const { Scalar } = await import('@scalar/hono-api-reference');
+  // ...
+}
+```
+
+This means UI libraries are loaded on the **first HTTP request** to the documentation endpoint, not at application startup. This keeps startup time fast and avoids loading unused UI libraries (only the configured provider's library is ever imported).
+
+#### ScalarUIProvider Title Mapping
+
+The `ScalarUIProvider` maps the `title` field to `pageTitle` when calling the Scalar renderer:
+
+```typescript
+const { title, url, ...customConfig } = config;
+return Scalar({ url, pageTitle: title, ...customConfig })(context, next);
+```
+
+This is a quirk to be aware of if you are inspecting the rendered output or writing custom UI providers -- Scalar uses `pageTitle` instead of `title`.
+
+### UIProviderFactory API
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getInstance()` | `static () => UIProviderFactory` | Returns singleton instance |
+| `register()` | `(opts: { type: string }) => void` | Instantiates and registers a UI provider (idempotent) |
+| `getProvider()` | `(opts: IGetProviderParams) => IUIProvider` | Returns registered provider or throws |
+| `getRegisteredProviders()` | `() => string[]` | Lists all registered provider type keys |
+
+#### register() Idempotency
+
+The `register()` method is idempotent. If a provider of the given type is already registered, it logs a warning and returns without error:
+
+```typescript
+register(opts: { type: string }): void {
+  if (this.isBound(opts.type)) {
+    this.logger
+      .for(this.register.name)
+      .warn('Skip registering BOUNDED Document UI | type: %s', opts.type);
+    return;
+  }
+  // ... instantiate and store the provider
+}
+```
+
+This means calling `register({ type: 'scalar' })` multiple times is safe and will not create duplicate provider instances.
+
+### IUIProvider Interface
+
+```typescript
+interface IUIProvider {
+  render(context: Context, config: IUIConfig, next: Next): Promise<Response | void>;
+}
+
+interface IUIConfig {
+  title: string;     // App name from package.json
+  url: string;       // Full URL to OpenAPI JSON endpoint
+  [key: string]: any; // Additional config from uiConfig option
+}
+```
+
+### Security Scheme Registration
+
+The component auto-registers two OpenAPI security schemes:
+
+```typescript
+// JWT Bearer
+rootRouter.openAPIRegistry.registerComponent('securitySchemes', 'jwt', {
+  type: 'http',
+  scheme: 'bearer',
+  bearerFormat: 'JWT',
+});
+
+// Basic Auth
+rootRouter.openAPIRegistry.registerComponent('securitySchemes', 'basic', {
+  type: 'http',
+  scheme: 'basic',
+});
+```
+
+This ensures routes using `authStrategies: ['jwt']` or `authStrategies: ['basic']` display the correct auth UI (lock icon + input fields) in the documentation.
+
+## Binding Keys
+
+| Key | Constant | Type | Required | Default |
+|-----|----------|------|----------|---------|
+| `@app/swagger/options` | `SwaggerBindingKeys.SWAGGER_OPTIONS` | `ISwaggerOptions` | No | See below |
+
+The `SwaggerComponent` constructor creates a default binding using the `Binding` fluent API:
+
+```typescript
+this.bindings = {
+  [SwaggerBindingKeys.SWAGGER_OPTIONS]: Binding.bind<ISwaggerOptions>({
+    key: SwaggerBindingKeys.SWAGGER_OPTIONS,
+  }).toValue(DEFAULT_SWAGGER_OPTIONS),
+};
+```
+
+Note that unlike `HealthCheckComponent`, `SwaggerComponent` does not pass `initDefault: { enable: true, container: application }` to `BaseComponent`. The default bindings stored in `this.bindings` are not automatically registered into the DI container. Instead, the `binding()` method reads from the container with `isOptional: true` and falls back to `DEFAULT_SWAGGER_OPTIONS` via the `??` operator.
+
+**Default value:**
+
+```typescript
+const DEFAULT_SWAGGER_OPTIONS: ISwaggerOptions = {
+  restOptions: {
+    base: { path: '/doc' },
+    doc: { path: '/openapi.json' },
+    ui: { path: '/explorer', type: 'scalar' },
+  },
+  explorer: {
+    openapi: '3.0.0',
+    info: {
+      title: 'API Documentation',
+      version: '1.0.0',
+      description: 'API documentation for your service',
+    },
+  },
+};
+```
+
+> [!NOTE]
+> The `explorer.info` values in `DEFAULT_SWAGGER_OPTIONS` are never used at runtime because `binding()` unconditionally overwrites `explorer.info` with data from `package.json`. They exist only as structural defaults.
+
+### Type Definitions
+
+```typescript
+type TDocumentUIType = TConstValue<typeof DocumentUITypes>;
+
+class DocumentUITypes {
+  static readonly SWAGGER = 'swagger';
+  static readonly SCALAR = 'scalar';
+  static readonly SCHEME_SET: Set<string>;
+  static isValid(input: string): boolean;
+}
+```
+
+`TDocumentUIType` is derived via `TConstValue`, which extracts the union of all `static readonly` string values from `DocumentUITypes`. This ensures the type stays in sync with the constants automatically.
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/doc/explorer` | Documentation UI (Scalar by default) |
+| `GET` | `/doc/openapi.json` | Raw OpenAPI specification |
+
+> [!NOTE]
+> These paths are based on the default configuration. If you customize `restOptions.base.path`, `restOptions.ui.path`, or `restOptions.doc.path`, the actual endpoints change accordingly.
+
+### Documentation UI Endpoint
+
+**Default path:** `/doc/explorer`
+
+Renders an interactive API documentation page using the configured UI provider (Scalar or Swagger UI). The UI fetches the OpenAPI spec from the JSON endpoint and renders it with full request/response exploration, authentication controls, and try-it-out functionality.
+
+### OpenAPI JSON Endpoint
+
+**Default path:** `/doc/openapi.json`
+
+Returns the raw OpenAPI JSON specification generated from all registered controller routes and their Zod schemas. This endpoint can be used by:
+- External API testing tools (Postman, Insomnia)
+- CI pipelines for API contract validation
+- Client SDK generators (openapi-generator, orval)
+- API gateway configuration
+
+## Troubleshooting
+
+### "Invalid document UI Type"
+
+**Cause:** The `restOptions.ui.type` value is not `'swagger'` or `'scalar'`. The `UIProviderFactory` only recognizes these two built-in providers. Note that a falsy value (empty string, `undefined`) does not trigger this error -- it silently falls back to `'swagger'` due to the `||` operator, not to the default `'scalar'`.
+
+**Fix:** Use a valid UI type:
+
+```typescript
+this.bind<ISwaggerOptions>({
+  key: SwaggerBindingKeys.SWAGGER_OPTIONS,
+}).toValue({
+  restOptions: {
+    base: { path: '/doc' },
+    doc: { path: '/openapi.json' },
+    ui: { path: '/explorer', type: 'scalar' }, // 'scalar' or 'swagger'
+  },
+  explorer: { openapi: '3.0.0' },
+});
+```
+
+### Documentation UI shows no routes
+
+**Cause:** Controllers are not defining routes with Zod schemas via `defineRoute` or `bindRoute`. Only routes registered through `@hono/zod-openapi` appear in the OpenAPI spec.
+
+**Fix:** Use `defineRoute` with Zod response schemas in your controllers:
+
+```typescript
+this.defineRoute({
+  configs: {
+    path: '/',
+    method: 'get',
+    responses: {
+      200: jsonContent({
+        description: 'Success',
+        schema: z.object({ message: z.string() }),
+      }),
+    },
+  },
+  handler: (c) => c.json({ message: 'ok' }, 200),
+});
+```
+
+### "Unknown UI Provider"
+
+**Cause:** The `UIProviderFactory.getProvider()` was called with a type that has not been registered. This typically happens if the component binding phase failed silently.
+
+**Fix:** Ensure the `SwaggerComponent` is registered in `preConfigure()` and that no errors occur during its `binding()` phase. Check the application logs for warnings from `UIProviderFactory`.
+
+### OpenAPI spec missing authentication schemes
+
+**Cause:** The `SwaggerComponent` auto-registers JWT and Basic security schemes. If the `AuthenticationComponent` is not registered, authenticated routes will not show auth UI in the documentation.
+
+**Fix:** Register `AuthenticationComponent` before `SwaggerComponent` in `preConfigure()` to ensure auth strategies are available when the Swagger component configures security schemes.
 
-By default, the documentation is available at the following endpoints:
+### explorer.info values not matching custom configuration
 
--   **/doc/explorer**: The documentation UI (`scalar` by default).
--   **/doc/openapi.json**: The raw OpenAPI specification.
+**Cause:** The `SwaggerComponent` unconditionally overwrites `explorer.info` with values from `package.json` during its `binding()` phase. Any values you set in `explorer.info` via the DI binding are discarded.
 
-These paths can be configured by providing custom `ISwaggerOptions`. This feature provides a powerful and flexible way to document your APIs, making them easier to consume and understand.
+**Fix:** Update your project's `package.json` fields (`name`, `version`, `description`, `author`) to control what appears in the API documentation info section. The component reads these via `application.getAppInfo()`.
 
 ## See Also
 
-- **Related Concepts:**
+- **Guides:**
   - [Components Overview](/guides/core-concepts/components) - Component system basics
   - [Controllers](/guides/core-concepts/controllers) - Defining OpenAPI routes
 
-- **Other Components:**
-  - [Components Index](./index) - All built-in components
+- **Components:**
+  - [All Components](./index) - Built-in components list
+  - [Authentication](./authentication/) - JWT/Basic auth for secured endpoints
 
-- **References:**
+- **Utilities:**
   - [Schema Utilities](/references/utilities/schema) - Response schema helpers
   - [JSX Utilities](/references/utilities/jsx) - HTML response schemas
 
 - **External Resources:**
   - [OpenAPI Specification](https://swagger.io/specification/) - OpenAPI standard
-  - [Scalar Documentation](https://github.com/scalar/scalar) - API documentation UI
+  - [Scalar Documentation](https://github.com/scalar/scalar) - Scalar API documentation UI
+  - [@hono/zod-openapi](https://github.com/honojs/middleware/tree/main/packages/zod-openapi) - Hono OpenAPI integration

package/wiki/references/components/template/api-page.md

@@ -0,0 +1,125 @@
+# API Reference Page Template (Tier 2 -- api.md)
+
+The "understand it deeply" page. A developer reads this on Day 30 when they need to understand how the component works internally, debug edge cases, or extend behavior. Contains architecture diagrams, full method signatures, internal lifecycle, and type definitions.
+
+Paired with [Setup](./setup-page), [Usage](./usage-page), and [Error Reference](./errors-page).
+
+## When to Use
+
+Always created alongside the other 3 pages for Tier 2 components.
+
+## Page Structure
+
+```markdown
+# {Component Name} -- API Reference
+
+> Architecture, method signatures, and internals for the [{Component Name}](./) component.
+
+## Architecture
+
+` ``
+  ┌─────────────────┐
+  │   Application    │
+  └────────┬────────┘
+           │ registers
+           ▼
+  ┌─────────────────┐     ┌──────────────┐
+  │   Component      │────▶│    Helper     │
+  └─────────────────┘     └──────────────┘
+` ``
+
+### {Flow Name} (e.g., "Authentication Flow", "Message Delivery Flow")
+
+1. Step-by-step explanation of the data flow
+2. What happens at each stage
+3. How components interact
+
+## {Public API Section} (e.g., "Server Helper API", "Strategy Registry")
+
+### `methodName()`
+
+` ``typescript
+methodName(opts: { param: Type }): ReturnType
+` ``
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `param` | `Type` | What it controls |
+
+**Returns:** Description of return value.
+
+### `anotherMethod()`
+
+` ``typescript
+anotherMethod(): void
+` ``
+
+Description of what this method does.
+
+## Types Reference
+
+### `IInterfaceName`
+
+` ``typescript
+interface IInterfaceName {
+  field: string;
+  optional?: number;
+}
+` ``
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `field` | `string` | What it represents |
+| `optional` | `number` | Optional description |
+
+## Internals
+
+### Component Lifecycle
+
+How the component initializes during application startup:
+
+1. **`constructor()`** -- What happens at instantiation
+2. **`binding()`** -- What gets registered with the DI container
+3. **`resolveBindings()`** -- How bindings are resolved
+4. **Post-start hook** -- What runs after the server starts (if applicable)
+
+### {Internal Mechanism} (e.g., "Token Encryption", "Redis Channel Architecture")
+
+Detailed explanation of a key internal mechanism.
+
+` ``typescript
+// Key implementation code
+` ``
+
+### {Another Internal}
+
+Description and code.
+
+## See Also
+
+- [Setup & Configuration](./) -- Quick reference, setup steps, configuration options
+- [Usage & Examples](./usage) -- Usage patterns, examples, API endpoints
+- [Error Reference](./errors) -- Error tables and troubleshooting
+
+- **Guides:**
+  - [Components](/guides/core-concepts/components) - Component system overview
+
+- **Components:**
+  - [All Components](../index) - Built-in components list
+```
+
+## Rules
+
+- **File name:** Always `api.md` inside the component directory
+- **Focus:** How it works internally. Architecture, methods, types, lifecycle
+- **Architecture section:** Required. Use ASCII art or Mermaid diagrams. Focus on data flow and component relationships
+- **Method signatures:** Show full TypeScript signatures with parameter tables
+- **Types Reference:** Include all public interfaces and types. Show the full interface definition plus a field description table
+- **Internals:** Explain the component lifecycle and key internal mechanisms. Include relevant source code snippets
+- **No setup steps** on this page -- those are in `index.md`
+- **No usage examples** on this page -- those are in `usage.md`
+- **No API endpoint specs** on this page -- those are in `usage.md`
+- **No error tables** on this page -- those are in `errors.md`
+- **No troubleshooting** on this page -- those are in `errors.md`
+- **No collapsible sections** -- show all content directly using `####` sub-headings for source code, verbose explanations
+- Use `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]`, `> [!IMPORTANT]` callouts