@venizia/ignis-docs 0.0.7-2 → 0.0.8-0

package/wiki/guides/core-concepts/dependency-injection.md

@@ -4,13 +4,13 @@ Dependency Injection (DI) enables loosely coupled, testable code by automaticall
 
 > **Deep Dive:** See [DI Reference](../../references/base/dependency-injection.md) for technical details on Container, Binding, and `@inject`.
 
-> **Standalone Package:** The core DI container is available as the standalone `@venizia/ignis-inversion` package for use outside the Ignis framework. See [Inversion Package Reference](/references/helpers/inversion/) for details.
+> **Standalone Package:** The core DI container is available as the standalone `@venizia/ignis-inversion` package for use outside the Ignis framework. See [Inversion Package Reference](/extensions/helpers/inversion/) for details.
 
 ## Core Concepts
 
 | Concept | Description |
 | :--- | :--- |
-| **Container** | The central registry for all your application's services and dependencies. The `Application` class itself acts as the container. |
+| **Container** | The central registry for all your application's services and dependencies. The `Application` class itself extends `Container`. |
 | **Binding** | The process of registering a class or value with the container under a specific key (e.g., `'services.UserService'`). |
 | **Injection**| The process of requesting a dependency from the container using the `@inject` decorator. |
 
@@ -42,6 +42,13 @@ graph TD
     end
 ```
 
+### Instantiation Algorithm (Two-Phase)
+
+When the container instantiates a class, it follows a two-phase process:
+
+1. **Constructor injection** -- Reads `@inject` metadata from the class, sorts by parameter index, resolves each dependency from the container, and passes them as constructor arguments.
+2. **Property injection** -- After construction, reads property metadata and assigns each dependency to the decorated properties.
+
 ## Binding Dependencies
 
 Before a dependency can be injected, it must be **bound** to the container. This is typically done in the `preConfigure` method of your `Application` class.
@@ -50,13 +57,13 @@ Before a dependency can be injected, it must be **bound** to the container. This
 
 The `Application` class provides helper methods for common resource types. These automatically create a binding with a conventional key.
 
-| Method | Default Key |
-| :--- | :--- |
-| `app.service(UserService)` | `services.UserService` |
-| `app.repository(UserRepository)` | `repositories.UserRepository` |
-| `app.dataSource(PostgresDataSource)` | `datasources.PostgresDataSource` |
-| `app.controller(UserController)` | `controllers.UserController` |
-| `app.component(MyComponent)` | `components.MyComponent` |
+| Method | Default Key | Default Scope |
+| :--- | :--- | :--- |
+| `app.service(UserService)` | `services.UserService` | Transient |
+| `app.repository(UserRepository)` | `repositories.UserRepository` | Transient |
+| `app.dataSource(PostgresDataSource)` | `datasources.PostgresDataSource` | **Singleton** |
+| `app.controller(UserController)` | `controllers.UserController` | Transient |
+| `app.component(MyComponent)` | `components.MyComponent` | **Singleton** |
 
 All these methods accept an optional second parameter to customize the binding key:
 
@@ -85,15 +92,29 @@ this.bind<string>({ key: 'API_KEY' }).toValue('my-secret-api-key');
 
 You can control the lifecycle of your dependencies with scopes.
 
--   **`TRANSIENT`** (default): A new instance is created every time the dependency is injected.
--   **`SINGLETON`**: A single instance is created once and reused for all subsequent injections.
+-   **`TRANSIENT`** (default): A new instance is created every time the dependency is resolved.
+-   **`SINGLETON`**: A single instance is created once and cached. All subsequent resolutions return the same instance.
 
 ```typescript
+import { BindingScopes } from '@venizia/ignis-inversion';
+
 this.bind({ key: 'services.MySingletonService' })
   .toClass(MySingletonService)
   .setScope(BindingScopes.SINGLETON); // Use SINGLETON for this service
 ```
 
+### Binding Tags
+
+Bindings are automatically tagged with their namespace prefix. For example, a binding with key `'services.UserService'` is auto-tagged with `'services'`. You can also add custom tags:
+
+```typescript
+this.bind({ key: 'services.UserService' })
+  .toClass(UserService)
+  .setTags('critical', 'user-domain');
+```
+
+Tags are used by the container's `findByTag()` method to discover bindings by category.
+
 ## Injecting Dependencies
 
 `Ignis` provides the `@inject` decorator to request dependencies from the container.
@@ -103,16 +124,16 @@ this.bind({ key: 'services.MySingletonService' })
 This makes dependencies explicit and ensures they are available right away.
 
 ```typescript
-import { BaseController, controller, inject } from '@venizia/ignis';
+import { BaseRestController, controller, inject } from '@venizia/ignis';
 import { UserService } from '../services/user.service';
 
 @controller({ path: '/users' })
-export class UserController extends BaseController {
+export class UserController extends BaseRestController {
   constructor(
     @inject({ key: 'services.UserService' })
     private userService: UserService
   ) {
-    super({ scope: UserController.name, path: '/users' });
+    super({ scope: UserController.name });
   }
 
   // ... you can now use this.userService
@@ -130,34 +151,56 @@ import { UserService } from '../services/user.service';
 export class UserComponent {
   @inject({ key: 'services.UserService' })
   private userService: UserService;
-  
+
   // ...
 }
 ```
 
+### Optional Dependencies
+
+Mark a dependency as optional to avoid errors when it's not bound:
+
+```typescript
+constructor(
+  @inject({ key: 'services.CacheService', isOptional: true })
+  private cache?: CacheService
+) {
+  super({ scope: MyService.name });
+  // cache will be undefined if not bound
+}
+```
+
 ## Providers
 
-Providers are used for dependencies that require complex setup logic. A provider is a class that implements a `value()` method, which is responsible for creating and returning the dependency instance.
+Providers are used for dependencies that require complex setup logic. A provider can be either a factory function or a class that implements the `IProvider<T>` interface with a `value()` method.
 
-### Creating a Custom Provider
+### Factory Function Provider
 
 ```typescript
-import { BaseProvider, inject, Container, IConfig } from '@venizia/ignis';
-import { ThirdPartyApiClient } from '../services/api-client.service';
-
-// Assume IConfig is a configuration object we've bound elsewhere
-@injectable() // Make the provider itself injectable
-export class ApiClientProvider extends BaseProvider<ThirdPartyApiClient> {
-  @inject({ key: 'configs.api' })
-  private apiConfig: IConfig;
-  
-  // The container calls this method to get the instance
+// In your application class
+this.bind<ThirdPartyApiClient>({ key: 'services.ApiClient' })
+  .toProvider((container) => {
+    const config = container.get<IConfig>({ key: 'configs.api' });
+    return new ThirdPartyApiClient({
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl,
+    });
+  });
+```
+
+### Class-Based Provider
+
+```typescript
+import { IProvider, Container } from '@venizia/ignis-inversion';
+
+export class ApiClientProvider implements IProvider<ThirdPartyApiClient> {
   value(container: Container): ThirdPartyApiClient {
+    const config = container.get<IConfig>({ key: 'configs.api' });
     const client = new ThirdPartyApiClient({
-      apiKey: this.apiConfig.apiKey,
-      baseUrl: this.apiConfig.baseUrl,
+      apiKey: config.apiKey,
+      baseUrl: config.baseUrl,
     });
-    client.connect(); // Perform initial setup
+    client.connect();
     return client;
   }
 }
@@ -192,7 +235,15 @@ container.bind({ key: 'services.Cache' })
 
 // Resolve dependencies
 const logger = container.get<LoggerService>({ key: 'services.Logger' });
-const apiKey = container.getSync<string>({ key: 'config.apiKey' });
+const apiKey = container.get<string>({ key: 'config.apiKey' });
+
+// Resolve multiple at once
+const [svcA, svcB] = container.gets<[ServiceA, ServiceB]>({
+  bindings: [
+    { key: 'services.A' },
+    { key: 'services.B', isOptional: true },
+  ],
+});
 ```
 
 ### Use Cases
@@ -245,19 +296,33 @@ describe('UserService', () => {
 | **Use Case** | Main application | Testing, isolated modules, workers |
 
 > [!TIP]
-> The `Application` class extends `Container`, so all container methods (`bind`, `get`, `getSync`) are available on your application instance. Standalone containers are useful when you need isolation from the main application context.
+> The `Application` class extends `Container`, so all container methods (`bind`, `get`, `gets`, `resolve`, `findByTag`, `isBound`, `unbind`) are available on your application instance. Standalone containers are useful when you need isolation from the main application context.
+
+### Container API Summary
+
+| Method | Description |
+| :--- | :--- |
+| `bind<T>({ key })` | Create a new binding |
+| `get<T>({ key, isOptional? })` | Resolve a single dependency |
+| `gets<T>({ bindings })` | Resolve multiple dependencies at once |
+| `resolve<T>(cls)` | Instantiate a class with DI (alias for `instantiate`) |
+| `isBound({ key })` | Check if a key is bound |
+| `unbind({ key })` | Remove a binding |
+| `findByTag({ tag, exclude? })` | Find bindings by tag |
+| `clear()` | Clear all cached singleton instances |
+| `reset()` | Remove all bindings entirely |
 
 ## See Also
 
 - **Related Concepts:**
   - [Application](/guides/core-concepts/application/) - Application extends Container
-  - [Controllers](/guides/core-concepts/controllers) - Use DI for injecting services
+  - [Controllers](/guides/core-concepts/rest-controllers) - Use DI for injecting services
   - [Services](/guides/core-concepts/services) - Use DI for injecting repositories
   - [Providers](/references/base/providers) - Factory pattern for dynamic injection
 
 - **References:**
   - [Dependency Injection API](/references/base/dependency-injection) - Complete API reference
-  - [Inversion Helper](/references/helpers/inversion/) - DI container utilities
+  - [Inversion Helper](/extensions/helpers/inversion/) - DI container utilities
   - [Glossary](/guides/reference/glossary#dependency-injection-di) - DI concepts explained
 
 - **Tutorials:**

package/wiki/guides/core-concepts/grpc-controllers.md

@@ -0,0 +1,295 @@
+# gRPC Controllers
+
+Ignis provides first-class support for gRPC via the [ConnectRPC](https://connectrpc.com/) protocol. gRPC controllers use Protobuf service definitions for strongly-typed RPC methods, and are served over the same Hono HTTP server as REST controllers.
+
+> **Deep Dive:** See [gRPC Controllers Reference](../../references/base/grpc-controllers.md) for the complete API.
+
+> [!IMPORTANT]
+> The current version only supports **unary** RPCs (single request, single response) over HTTP/1.1 Connect protocol. Streaming methods (`@serverStream`, `@clientStream`, `@bidiStream`) have decorators defined for metadata registration, but will throw an error at runtime if used.
+
+## Peer Dependencies
+
+gRPC support requires the following packages to be installed:
+
+```bash
+bun add @connectrpc/connect @bufbuild/protobuf
+```
+
+## Enabling gRPC Transport
+
+To use gRPC controllers, you must enable the gRPC transport in your application configuration:
+
+```typescript
+import { ControllerTransports } from '@venizia/ignis';
+
+export const appConfigs: IApplicationConfigs = {
+  // ... other config
+  transports: [ControllerTransports.REST, ControllerTransports.GRPC],
+};
+```
+
+If `transports` is not specified, only `REST` is enabled by default. If gRPC controllers are discovered but the gRPC transport is not enabled, the framework will log an error warning.
+
+## Creating a gRPC Controller
+
+Extend `BaseGrpcController` and use the `@controller` decorator with `transport: ControllerTransports.GRPC` and a `service` reference to your generated Protobuf service definition.
+
+```typescript
+import { create } from '@bufbuild/protobuf';
+import {
+  BaseGrpcController,
+  ControllerTransports,
+  controller,
+  inject,
+  unary,
+  TRouteContext,
+} from '@venizia/ignis';
+import {
+  GreeterService,
+  SayHelloResponseSchema,
+  type SayHelloRequest,
+  type SayHelloResponse,
+} from './generated/greeter_pb';
+
+@controller({
+  path: '/grpc',
+  transport: ControllerTransports.GRPC,
+  service: GreeterService,
+})
+export class GreeterController extends BaseGrpcController {
+  constructor(
+    @inject({ key: 'services.GreeterService' })
+    private readonly greeterService: GreeterService,
+  ) {
+    super({ scope: 'GreeterController' });
+  }
+
+  override binding() {}
+
+  @unary({ configs: { name: 'sayHello' } })
+  async sayHello(opts: { request: SayHelloRequest; context: TRouteContext }): Promise<SayHelloResponse> {
+    const message = await this.greeterService.greet({ name: opts.request.name });
+    return create(SayHelloResponseSchema, { message });
+  }
+}
+```
+
+### Key Points
+
+- The `service` field in `@controller` must reference the generated ConnectRPC service definition (e.g., `GreeterService`)
+- The `path` determines the URL prefix where the gRPC service is mounted
+- `binding()` must be implemented (even if empty) -- it is called during `configure()`
+- Handler methods receive `{ request, context }` and return a Protobuf message object
+
+## RPC Method Decorators
+
+Ignis provides a decorator for each gRPC method type:
+
+- `@unary(opts)` -- Single request, single response. **This is the only supported method type** in the current version.
+- `@serverStream(opts)` -- Decorator exists for metadata, but throws at runtime.
+- `@clientStream(opts)` -- Decorator exists for metadata, but throws at runtime.
+- `@bidiStream(opts)` -- Decorator exists for metadata, but throws at runtime.
+- `@rpc(opts)` -- Generic RPC decorator where you specify the `method` in the configs.
+
+The `opts` object contains a `configs` property with at minimum a `name` field that matches the RPC method name in your Protobuf service definition. You can also specify `authenticate` and `authorize` options, just like REST routes.
+
+```typescript
+// Unary (supported)
+@unary({ configs: { name: 'sayHello' } })
+async sayHello(opts: { request: SayHelloRequest; context: TRouteContext }): Promise<SayHelloResponse> { ... }
+
+// With authentication
+@unary({
+  configs: {
+    name: 'getUser',
+    authenticate: { strategies: ['jwt'], mode: 'required' },
+  },
+})
+async getUser(opts: { request: GetUserRequest; context: TRouteContext }): Promise<GetUserResponse> { ... }
+
+// With authorization
+@unary({
+  configs: {
+    name: 'deleteUser',
+    authenticate: { strategies: ['jwt'] },
+    authorize: { resource: 'user', scopes: ['delete'] },
+  },
+})
+async deleteUser(opts: { request: DeleteUserRequest; context: TRouteContext }): Promise<DeleteUserResponse> { ... }
+```
+
+## Transport Configuration
+
+The transport type is set via the `transport` field in the `@controller` decorator:
+
+```typescript
+// REST controller (default -- transport can be omitted)
+@controller({ path: '/users' })
+
+// gRPC controller
+@controller({ path: '/grpc', transport: ControllerTransports.GRPC, service: MyService })
+```
+
+The `ControllerTransports` class provides the available transport constants:
+
+- `ControllerTransports.REST` -- Default HTTP/JSON transport
+- `ControllerTransports.GRPC` -- ConnectRPC transport
+
+## Manual Route Definition
+
+Just like REST controllers, gRPC controllers support manual route definition via `defineRoute` and `bindRoute`:
+
+```typescript
+import { GRPC } from '@venizia/ignis-helpers';
+
+override binding() {
+  // Using defineRoute
+  this.defineRoute({
+    configs: { name: 'sayHello', method: GRPC.Methods.UNARY },
+    handler: async (opts) => {
+      return create(SayHelloResponseSchema, { message: `Hello ${opts.request.name}` });
+    },
+  });
+
+  // Using bindRoute (fluent API)
+  this.bindRoute({
+    configs: { name: 'getUser', method: GRPC.Methods.UNARY },
+  }).to({
+    handler: async (opts) => {
+      return create(GetUserResponseSchema, { name: 'John' });
+    },
+  });
+}
+```
+
+## Minimal Controller (No DI)
+
+For simple services that don't need injected dependencies:
+
+```typescript
+import { create } from '@bufbuild/protobuf';
+import { BaseGrpcController, ControllerTransports, controller, unary } from '@venizia/ignis';
+import { EchoService, EchoResponseSchema, type EchoRequest, type EchoResponse } from './generated/echo_pb';
+
+@controller({
+  path: '/echo',
+  transport: ControllerTransports.GRPC,
+  service: EchoService,
+})
+export class EchoController extends BaseGrpcController {
+  constructor() {
+    super({ scope: 'EchoController' });
+  }
+
+  override binding() {}
+
+  @unary({ configs: { name: 'echo' } })
+  async echo(opts: { request: EchoRequest }): Promise<EchoResponse> {
+    return create(EchoResponseSchema, { message: opts.request.message });
+  }
+}
+```
+
+## Key Differences from REST Controllers
+
+| Aspect | REST Controller | gRPC Controller |
+| :--- | :--- | :--- |
+| **Base class** | `BaseRestController` | `BaseGrpcController` |
+| **Router** | `OpenAPIHono` | `Hono` (plain) |
+| **Route identifier** | `path` + HTTP method | `name` (Protobuf method name) |
+| **Handler signature** | `(c: TRouteContext) => Response` | `(opts: { request, context }) => ResponseMessage` |
+| **Response format** | `c.json()` calls | Protobuf message objects via `create()` |
+| **Schema** | Zod + OpenAPI | Protobuf (`@bufbuild/protobuf`) |
+| **`binding()` method** | Optional (can use decorators only) | Must be implemented (even if empty) |
+| **`configure()` return** | `OpenAPIHono` router | `void` (adapter mounted internally) |
+| **Peer dependencies** | None | `@connectrpc/connect`, `@bufbuild/protobuf` |
+
+## Protobuf Setup
+
+gRPC controllers require Protobuf service definitions. The typical workflow:
+
+### 1. Define your `.proto` file
+
+```protobuf
+// proto/greeter.proto
+syntax = "proto3";
+
+package greeter;
+
+service GreeterService {
+  rpc SayHello (SayHelloRequest) returns (SayHelloResponse);
+  rpc ListUsers (ListUsersRequest) returns (ListUsersResponse);
+}
+
+message SayHelloRequest {
+  string name = 1;
+}
+
+message SayHelloResponse {
+  string message = 1;
+}
+
+message ListUsersRequest {}
+
+message ListUsersResponse {
+  repeated User users = 1;
+}
+
+message User {
+  string id = 1;
+  string name = 2;
+  string email = 3;
+}
+```
+
+### 2. Generate TypeScript code
+
+Use [Buf](https://buf.build/) to generate TypeScript from your `.proto` files:
+
+```yaml
+# buf.gen.yaml
+version: v2
+plugins:
+  - remote: buf.build/bufbuild/es
+    out: src/controllers/greeter/generated
+```
+
+```bash
+npx buf generate src/controllers/greeter/proto
+```
+
+### 3. Use the generated types in your controller
+
+The generated `*_pb.ts` files export service definitions, message schemas, and TypeScript types that you use directly in your controller (as shown in the examples above).
+
+## Client Usage
+
+You can test gRPC controllers using the ConnectRPC client:
+
+```typescript
+import { createClient } from '@connectrpc/connect';
+import { createConnectTransport } from '@connectrpc/connect-web';
+import { GreeterService } from './controllers/greeter/generated/greeter_pb';
+
+const transport = createConnectTransport({
+  baseUrl: 'http://localhost:3000',
+});
+
+const client = createClient(GreeterService, transport);
+
+const response = await client.sayHello({ name: 'World' });
+console.log(response.message); // "Hello, World!"
+```
+
+## See Also
+
+- **Related Concepts:**
+  - [Application](/guides/core-concepts/application/) - Registering controllers and enabling transports
+  - [REST Controllers](/guides/core-concepts/rest-controllers) - HTTP/JSON controllers
+  - [Services](/guides/core-concepts/services) - Business logic layer called by controllers
+  - [Dependency Injection](/guides/core-concepts/dependency-injection) - Injecting services into controllers
+
+- **References:**
+  - [BaseGrpcController API](/references/base/grpc-controllers) - Complete gRPC controller API reference
+  - [Authentication](/extensions/components/authentication/) - Securing gRPC endpoints
+  - [Authorization](/extensions/components/authorization/) - Role-based access control for RPCs

package/wiki/guides/core-concepts/persistent/datasources.md

@@ -27,7 +27,7 @@ interface IDSConfigs {
 }
 
 @datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
@@ -64,9 +64,11 @@ export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, I
 
 **How auto-discovery works:**
 
-1. `@repository` decorators register model-datasource bindings
-2. When `configure()` is called, `getSchema()` collects all bound models
-3. Drizzle is initialized with the complete schema
+1. `@repository` decorators register model-datasource bindings in the `MetadataRegistry`
+2. When `configure()` is called, `getSchema()` invokes `discoverSchema()` which calls `MetadataRegistry.buildSchema({ dataSource })` to collect all bound models and their relations
+3. Drizzle is initialized with the complete schema (tables + Drizzle relations)
+
+You can disable auto-discovery per datasource via `@datasource({ driver: 'node-postgres', autoDiscovery: false })`.
 
 ## Manual Schema (Optional)
 
@@ -74,7 +76,7 @@ If you need explicit control, you can still provide schema manually:
 
 ```typescript
 @datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
@@ -89,6 +91,21 @@ export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, I
 }
 ```
 
+## DataSource Hierarchy
+
+```
+AbstractDataSource extends BaseHelper
+  └── BaseDataSource
+        ├── configure()               # Setup pool + Drizzle connector (abstract)
+        ├── getConnectionString()     # Build connection URL (abstract)
+        ├── getSchema()               # Auto-discover from @repository bindings
+        ├── discoverSchema()          # Internal: reads MetadataRegistry
+        ├── hasDiscoverableModels()   # Check if any repos reference this DS
+        ├── beginTransaction(opts?)   # Start transaction with isolation level
+        ├── getConnector()            # Get Drizzle connector
+        └── getSettings()            # Get connection config
+```
+
 ## Registering a DataSource
 
 ```typescript
@@ -100,18 +117,20 @@ export class Application extends BaseApplication {
 }
 ```
 
+DataSources are bound as **singletons** to ensure connection pool sharing across the application.
+
 ## Supported Drivers
 
 | Driver | Package | Status |
 |--------|---------|--------|
-| `node-postgres` | `pg` | ✅ Supported |
+| `node-postgres` | `pg` | Supported |
 | `mysql2` | `mysql2` | Planned |
 | `better-sqlite3` | `better-sqlite3` | Planned |
 
 ## DataSource Template
 
 ```typescript
-import { BaseDataSource, datasource, TNodePostgresConnector, ValueOrPromise } from '@venizia/ignis';
+import { BaseDataSource, datasource, ValueOrPromise } from '@venizia/ignis';
 import { drizzle } from 'drizzle-orm/node-postgres';
 import { Pool } from 'pg';
 
@@ -124,7 +143,7 @@ interface IDSConfigs {
 }
 
 @datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,

package/wiki/guides/core-concepts/persistent/models.md

@@ -208,6 +208,35 @@ const [fullUser] = await connector
 For complete hidden properties documentation, see the [Models Reference](../../../references/base/models.md#hidden-properties).
 :::
 
+## Default Filter
+
+Apply automatic filters to all repository queries. This is commonly used for soft-delete patterns:
+
+```typescript
+@model({
+  type: 'entity',
+  settings: {
+    defaultFilter: { where: { isDeleted: false } },
+    hiddenProperties: ['deletedAt'],
+  },
+})
+export class Article extends BaseEntity<typeof Article.schema> {
+  // ...
+}
+```
+
+The default filter is applied automatically to all read operations. Bypass it with `shouldSkipDefaultFilter: true` in the options:
+
+```typescript
+// Normal query - auto-filters out soft-deleted records
+const articles = await articleRepo.find({});
+
+// Include deleted records
+const allArticles = await articleRepo.find({
+  options: { shouldSkipDefaultFilter: true },
+});
+```
+
 ## Authorization Settings
 
 Declare your model's authorization principal directly in `@model` settings. The decorator auto-populates `AUTHORIZATION_SUBJECT` for type-safe references in route configs:
@@ -237,9 +266,22 @@ authorize: {
 ```
 
 :::tip
-For full authorization integration details, see the [Authorization Usage Reference](../../../references/components/authorization/usage#model-based-resource-references).
+For full authorization integration details, see the [Authorization Usage Reference](../../../extensions/components/authorization/usage#model-based-resource-references).
 :::
 
+## Model Metadata Types
+
+The `@model` decorator accepts the following metadata:
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `type` | `'entity' \| 'view'` | Whether this is a table or a database view |
+| `tableName` | `string` | Optional explicit table name |
+| `skipMigrate` | `boolean` | Skip this model during migrations |
+| `settings.hiddenProperties` | `string[]` | Properties excluded from all query results |
+| `settings.defaultFilter` | `TFilter` | Default filter auto-applied to all queries |
+| `settings.authorize.principal` | `string` | Authorization subject name for this model |
+
 ## Model Template
 
 ```typescript