@venizia/ignis-docs 0.0.7 → 0.0.8-0

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

@@ -71,13 +71,26 @@ export class UserRepository extends ReadableRepository<typeof User.schema> {
 > - After the first argument, you can inject any additional dependencies you need
 > - When `@inject` is at param index 0, auto-injection is skipped
 
-## Repository Types
+## Repository Hierarchy
+
+```
+AbstractRepository (base + mixins: FieldsVisibilityMixin + DefaultFilterMixin)
+  ↓
+ReadableRepository (read-only: find, findOne, findById, count, existsWith)
+  ↓
+PersistableRepository (+ create, updateById, updateAll)
+  ↓
+DefaultCRUDRepository (+ deleteById, deleteAll) — recommended default
+  ↓
+SoftDeletableRepository (overrides delete to set deletedAt timestamp)
+```
 
 | Type | Description |
 |------|-------------|
-| `DefaultCRUDRepository` | Full read/write operations |
-| `ReadableRepository` | Read-only operations |
-| `PersistableRepository` | Write operations only |
+| `ReadableRepository` | Read-only operations. Write operations throw errors. |
+| `PersistableRepository` | Read + write operations (create, update). Extends ReadableRepository. |
+| `DefaultCRUDRepository` | Full CRUD including delete. Extends PersistableRepository. **Recommended for most use cases.** |
+| `SoftDeletableRepository` | Extends DefaultCRUDRepository. Overrides delete to set `deletedAt` timestamp instead of physically removing records. |
 
 ## Querying Data
 
@@ -134,6 +147,32 @@ await repo.updateById({
 await repo.deleteById({ id: 'uuid-here' });
 ```
 
+## Extra Options
+
+All repository operations accept an `options` parameter with these fields:
+
+| Option | Type | Description |
+| :--- | :--- | :--- |
+| `transaction` | `ITransaction` | Transaction context for atomic operations |
+| `shouldReturn` | `boolean` | Whether to return created/updated data (default: `true`) |
+| `shouldQueryRange` | `boolean` | Return `{ data, range: { total, skip, limit } }` for pagination |
+| `shouldSkipDefaultFilter` | `boolean` | Bypass the model's default filter (e.g., soft delete) |
+
+```typescript
+// Create without returning data (faster for bulk inserts)
+await repo.create({
+  data: bulkData,
+  options: { shouldReturn: false }
+});
+
+// Query with pagination range
+const result = await repo.find({
+  filter: { limit: 20, skip: 0 },
+  options: { shouldQueryRange: true }
+});
+// result = { data: [...], range: { total: 150, skip: 0, limit: 20 } }
+```
+
 ## Querying with Relations
 
 Use `include` to fetch related data. The relation name must match what you defined in `static relations`:
@@ -162,6 +201,34 @@ export class Application extends BaseApplication {
 }
 ```
 
+## SoftDeletableRepository
+
+For soft-delete patterns, use `SoftDeletableRepository` which overrides delete operations to set a `deletedAt` timestamp instead of physically removing records:
+
+```typescript
+import { SoftDeletableRepository, repository, model, BaseEntity } from '@venizia/ignis';
+import { pgTable, timestamp } from 'drizzle-orm/pg-core';
+
+@model({
+  type: 'entity',
+  settings: {
+    hiddenProperties: ['deletedAt'],
+    defaultFilter: { where: { deletedAt: null } },
+  },
+})
+export class Category extends BaseEntity<typeof Category.schema> {
+  static override schema = pgTable('Category', {
+    ...generateIdColumnDefs({ id: { dataType: 'string' } }),
+    ...generateTzColumnDefs(),
+    deletedAt: timestamp('deleted_at', { withTimezone: true }),
+    name: text('name').notNull(),
+  });
+}
+
+@repository({ dataSource: PostgresDataSource, model: Category })
+export class CategoryRepository extends SoftDeletableRepository<typeof Category.schema> {}
+```
+
 ## Repository Template
 
 ```typescript
@@ -177,7 +244,7 @@ export class MyModelRepository extends DefaultCRUDRepository<typeof MyModel.sche
 
 ### Performance: Core API Optimization
 
-Ignis automatically optimizes "flat" queries (no relations, no field selection) by using Drizzle's Core API. This provides **~15-20% faster** queries for simple reads.
+Ignis automatically optimizes "flat" queries (no relations, no field selection) by using Drizzle's Core API. This provides **~15-20% faster** queries for simple reads. The `canUseCoreAPI()` method on `ReadableRepository` determines when this optimization applies.
 
 ### Modular Persistence with Components
 
@@ -186,9 +253,9 @@ Bundle related persistence resources into Components for better organization:
 ```typescript
 export class UserManagementComponent extends BaseComponent {
   override binding() {
-    this.application.dataSource(PostgresDataSource);
-    this.application.repository(UserRepository);
-    this.application.repository(ProfileRepository);
+    this._application.dataSource(PostgresDataSource);
+    this._application.repository(UserRepository);
+    this._application.repository(ProfileRepository);
   }
 }
 ```

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

@@ -4,10 +4,10 @@ Ignis supports explicit transaction objects that can be passed across multiple s
 
 ## Using Transactions
 
-To use transactions, start one from a repository or datasource, and then pass it to subsequent operations via the `options` parameter.
+To use transactions, start one from a datasource (via the repository's `beginTransaction` method), and then pass it to subsequent operations via the `options` parameter.
 
 ```typescript
-// 1. Start a transaction
+// 1. Start a transaction from the datasource (accessed through a repository)
 const tx = await userRepo.beginTransaction({
   isolationLevel: 'SERIALIZABLE' // Optional, defaults to 'READ COMMITTED'
 });
@@ -38,6 +38,20 @@ try {
 }
 ```
 
+## Transaction Object
+
+The transaction object returned by `beginTransaction()` has the following properties:
+
+| Property/Method | Type | Description |
+| :--- | :--- | :--- |
+| `connector` | `TNodePostgresConnector` | A Drizzle connector bound to the transaction's database client |
+| `isolationLevel` | `TIsolationLevel` | The isolation level of this transaction |
+| `isActive` | `boolean` | Whether the transaction is still active (not yet committed/rolled back) |
+| `commit()` | `Promise<void>` | Commit the transaction and release the connection |
+| `rollback()` | `Promise<void>` | Rollback the transaction and release the connection |
+
+Calling `commit()` or `rollback()` on an already-ended transaction throws an error.
+
 ## Isolation Levels
 
 Ignis supports standard PostgreSQL isolation levels:
@@ -48,10 +62,12 @@ Ignis supports standard PostgreSQL isolation levels:
 | `REPEATABLE READ` | Queries see a snapshot as of the start of the transaction. | Reports, consistent reads across multiple queries. |
 | `SERIALIZABLE` | Strictest level. Emulates serial execution. | Financial transactions, critical data integrity. |
 
+Note: `READ UNCOMMITTED` is technically accepted but behaves as `READ COMMITTED` in PostgreSQL.
+
 ## Best Practices
 
-1.  **Always use `try...catch...finally`**: Ensure `rollback()` is called on error to release the connection.
-2.  **Keep it short**: Long-running transactions hold database locks and connections.
+1.  **Always use `try...catch`**: Ensure `rollback()` is called on error to release the connection back to the pool.
+2.  **Keep it short**: Long-running transactions hold database connections from the pool and can cause connection exhaustion.
 3.  **Pass explicit options**: When calling other services inside a transaction, ensure they accept and use the `transaction` option.
 
 ```typescript
@@ -109,19 +125,19 @@ export class OrderService extends BaseService {
 
 ```typescript
 @controller({ path: '/orders' })
-export class OrderController extends BaseController {
+export class OrderController extends BaseRestController {
   constructor(
     @inject({ key: 'repositories.OrderRepository' })
     private _orderRepository: OrderRepository,
     @inject({ key: 'services.OrderService' })
     private _orderService: OrderService,
   ) {
-    super({ scope: OrderController.name, path: '/orders' });
+    super({ scope: OrderController.name });
   }
 
   @post({ configs: OrderRoutes.CREATE })
   async createOrder(c: TRouteContext) {
-    const body = c.req.valid<{ order: any; items: any[] }>('json'); // Use explicit types for better safety
+    const body = c.req.valid<{ order: any; items: any[] }>('json');
 
     const tx = await this._orderRepository.beginTransaction({
       isolationLevel: 'SERIALIZABLE',
@@ -144,6 +160,20 @@ export class OrderController extends BaseController {
 }
 ```
 
+## How Transactions Work Internally
+
+When you pass a `transaction` option to a repository method, the repository uses the transaction's `connector` (a Drizzle instance bound to the transaction's `PoolClient`) instead of the default datasource connector. This ensures all operations within the transaction use the same database connection and see a consistent view of the data.
+
+```typescript
+// Inside AbstractRepository (simplified)
+protected resolveConnector(opts?: { transaction?: ITransaction }) {
+  if (opts?.transaction) {
+    return opts.transaction.connector;
+  }
+  return this.dataSource.connector;
+}
+```
+
 > **Deep Dive:** See [Repository Reference](../../../references/base/repositories/) for more transaction options and patterns.
 
 ## See Also
@@ -151,7 +181,7 @@ export class OrderController extends BaseController {
 - **Related Concepts:**
   - [Repositories](/guides/core-concepts/persistent/repositories) - Provide transaction API
   - [Services](/guides/core-concepts/services) - Orchestrate transactional operations
-  - [Controllers](/guides/core-concepts/controllers) - Initiate transactions from HTTP handlers
+  - [Controllers](/guides/core-concepts/rest-controllers) - Initiate transactions from HTTP handlers
   - [DataSources](/guides/core-concepts/persistent/datasources) - Database connections
 
 - **References:**

package/wiki/guides/core-concepts/{controllers.md → rest-controllers.md}

@@ -1,23 +1,22 @@
-# Controllers
+# REST Controllers
 
-Controllers handle HTTP requests and return responses - they're your API endpoints.
+REST controllers handle incoming HTTP requests and return JSON responses -- they are your API endpoints. This is the default transport in Ignis and covers the majority of use cases.
 
-> **Deep Dive:** See [Controllers Reference](../../references/base/controllers.md) for advanced patterns.
+> **Deep Dive:** See [REST Controllers Reference](../../references/base/controllers.md) for the complete API.
 
-## Creating a Controller
+## Creating a REST Controller
 
-Extend `BaseController` and use decorators to define routes:
+Extend `BaseRestController` and use decorators to define routes:
 
 ```typescript
-import { BaseController, controller, get, jsonResponse, z } from '@venizia/ignis';
+import { BaseRestController, controller, get, jsonResponse, z, TRouteContext } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
-import { Context } from 'hono';
 
 @controller({ path: '/users' })
-export class UserController extends BaseController {
+export class UserController extends BaseRestController {
   constructor() {
-    // It's good practice to pass a scope for logging
-    super({ scope: UserController.name, path: '/users' });
+    // scope is used for logging; path can be omitted if @controller provides it
+    super({ scope: UserController.name });
   }
 
   @get({
@@ -29,12 +28,13 @@ export class UserController extends BaseController {
       }),
     },
   })
-  getAllUsers(c: Context) {
+  getAllUsers(c: TRouteContext) {
     return c.json([{ id: '1', name: 'John Doe' }], HTTP.ResultCodes.RS_2.Ok);
   }
 }
 ```
-Notice that the `binding()` method is no longer needed when using decorators.
+
+Notice that the `binding()` method is no longer needed when using decorators. The path is resolved from the `@controller` decorator metadata first, then falls back to the constructor `path` option.
 
 ## Controller Lifecycle
 
@@ -42,8 +42,8 @@ Controllers have a simple and predictable lifecycle managed by the application.
 
 | Stage | Method | Description |
 | :--- | :--- | :--- |
-| **1. Instantiation** | `constructor(opts)` | The controller is created by the DI container. Dependencies are injected, and you call `super()` to initialize the internal Hono router. |
-| **2. Configuration**| `registerControllers` phase | The application automatically discovers and registers all routes defined with decorators (`@get`, `@post`, etc.) on your controller methods. If you have routes defined manually inside `binding()`, that method is also called during this phase. **Note:** If you exclusively use decorators for routing, the `binding()` method can be omitted from your controller. |
+| **1. Instantiation** | `constructor(opts)` | The controller is created by the DI container. Dependencies are injected, and `super()` initializes the internal `OpenAPIHono` router. The `path` is resolved from `@controller` decorator metadata, falling back to the constructor option. |
+| **2. Configuration**| `configure()` | The application calls `configure()` which invokes `binding()` (for manual routes) and `registerRoutesFromRegistry()` (for decorator routes). This method is **idempotent** -- calling it multiple times has no effect after the first call. |
 
 ## Defining Routes with Decorators (Recommended)
 
@@ -71,14 +71,13 @@ The `opts` object contains a `configs` property that defines the route's path, r
 For optimal organization and type safety, define your route configurations in a constant with `as const`. This allows TypeScript to precisely infer the types for your request data and expected responses within your handler methods.
 
 ```typescript
-import { BaseController, controller, get, post, jsonContent, jsonResponse, TRouteContext } from '@venizia/ignis';
+import { BaseRestController, controller, get, post, jsonContent, jsonResponse, TRouteContext } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
 import { z } from '@hono/zod-openapi';
 
 // Define route configs as const for type inference
 const TestRoutes = {
   GET_DATA: {
-    method: HTTP.Methods.GET,
     path: '/',
     responses: jsonResponse({
       description: 'A simple message',
@@ -86,7 +85,6 @@ const TestRoutes = {
     }),
   },
   CREATE_ITEM: {
-    method: HTTP.Methods.POST,
     path: '/',
     request: {
       body: jsonContent({
@@ -102,9 +100,9 @@ const TestRoutes = {
 } as const; // Crucial for strict type inference!
 
 @controller({ path: '/my-items' })
-export class MyItemsController extends BaseController {
+export class MyItemsController extends BaseRestController {
   constructor() {
-    super({ scope: MyItemsController.name, path: '/my-items' });
+    super({ scope: MyItemsController.name });
   }
 
   @get({ configs: TestRoutes.GET_DATA })
@@ -171,7 +169,7 @@ import { HTTP } from '@venizia/ignis-helpers';
 const GetUsersRoute = {
   path: '/',
   method: 'get',
-  authStrategies: [Authentication.STRATEGY_JWT],
+  authenticate: { strategies: [Authentication.STRATEGY_JWT] },
   responses: jsonResponse({
     description: 'List of all users',
     schema: z.array(z.object({ id: z.number(), name: z.string() })),
@@ -197,7 +195,7 @@ import { HTTP } from '@venizia/ignis-helpers';
 // ... inside the binding() method
 
 const GetUserByIdRoute = {
-  path: '/:id',
+  path: '/{id}',
   method: 'get',
   responses: jsonResponse({
     description: 'A single user',
@@ -264,12 +262,12 @@ The `ControllerFactory.defineCrudController` method automatically sets up the fo
 | :--- | :--- | :--- | :--- |
 | `count` | `GET` | `/count` | Get the number of records matching a filter. |
 | `find` | `GET` | `/` | Retrieve all records matching a filter. |
-| `findById` | `GET` | `/:id` | Retrieve a single record by its ID. |
+| `findById` | `GET` | `/{id}` | Retrieve a single record by its ID. |
 | `findOne` | `GET` | `/find-one` | Retrieve a single record matching a filter. |
 | `create` | `POST` | `/` | Create a new record. |
-| `updateById` | `PATCH` | `/:id` | Update a single record by its ID. |
+| `updateById` | `PATCH` | `/{id}` | Update a single record by its ID. |
 | `updateBy` | `PATCH` | `/` | Update multiple records matching a `where` filter. |
-| `deleteById` | `DELETE` | `/:id` | Delete a single record by its ID. |
+| `deleteById` | `DELETE` | `/{id}` | Delete a single record by its ID. |
 | `deleteBy` | `DELETE` | `/` | Delete multiple records matching a `where` filter. |
 
 :::info Customization
@@ -357,7 +355,7 @@ export const MainLayout: FC<PropsWithChildren<MainLayoutProps>> = ({ title, chil
         </header>
         <main>{children}</main>
         <footer>
-          <p>© 2025 My App</p>
+          <p>&copy; 2025 My App</p>
         </footer>
       </body>
     </html>
@@ -373,7 +371,7 @@ When you define Zod schemas in your route's `request` configuration (whether wit
 
 ```typescript
 import { z } from '@hono/zod-openapi';
-import { jsonContent, put } from '@venizia/ignis';
+import { jsonContent, put, TRouteContext } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
 
 // ... inside a controller class
@@ -382,8 +380,7 @@ const UserSchema = z.object({ name: z.string(), email: z.string().email() });
 
 @put({
   configs: {
-    path: '/:id',
-    method: 'put',
+    path: '/{id}',
     request: {
       params: z.object({ id: z.string() }),
       query: z.object({ notify: z.string().optional() }),
@@ -392,7 +389,7 @@ const UserSchema = z.object({ name: z.string(), email: z.string().email() });
     // ... responses
   },
 })
-updateUser(c: Context) {
+updateUser(c: TRouteContext) {
   // Access validated data from the request
   const { id } = c.req.valid('param');
   const { notify } = c.req.valid('query');
@@ -417,8 +414,7 @@ import { HTTP } from '@venizia/ignis-helpers';
 // ... inside a controller class
 
 const UpdateUserConfig = {
-  path: '/:id',
-  method: 'put',
+  path: '/{id}',
   request: {
     params: z.object({ id: z.string() }),
     query: z.object({ notify: z.string().optional() }),
@@ -453,11 +449,12 @@ Using `TRouteContext` provides a typed context object. By using `c.req.valid<T>(
   - [Application](/guides/core-concepts/application/) - Registering controllers
   - [Services](/guides/core-concepts/services) - Business logic layer called by controllers
   - [Dependency Injection](/guides/core-concepts/dependency-injection) - Injecting services into controllers
+  - [gRPC Controllers](/guides/core-concepts/grpc-controllers) - RPC-based controllers
 
 - **References:**
-  - [BaseController API](/references/base/controllers) - Complete API reference
+  - [BaseRestController API](/references/base/controllers) - Complete REST controller API reference
   - [Middlewares](/references/base/middlewares) - Request interceptors
-  - [Swagger Component](/references/components/swagger) - Auto-generate API docs
+  - [Swagger Component](/extensions/components/swagger) - Auto-generate API docs
   - [Schema Utilities](/references/utilities/schema) - Request/response helpers
 
 - **Tutorials:**

package/wiki/guides/core-concepts/services.md

@@ -15,7 +15,7 @@ Services contain the core business logic of your application. They orchestrate t
 
 ### Creating a Service
 
-To create a service, you extend the `BaseService` class and inject the repositories or other services it depends on.
+To create a service, extend the `BaseService` class and inject the repositories or other services it depends on.
 
 ```typescript
 import { BaseService, inject } from '@venizia/ignis';
@@ -27,9 +27,9 @@ import { TConfiguration } from '../models/entities';
 
 export class ConfigurationService extends BaseService {
   constructor(
-    @inject({ key: 'repositories.ConfigurationRepository' }) 
+    @inject({ key: 'repositories.ConfigurationRepository' })
     private configurationRepository: ConfigurationRepository,
-    @inject({ key: 'repositories.UserRepository' }) 
+    @inject({ key: 'repositories.UserRepository' })
     private userRepository: UserRepository,
     @inject({ key: 'services.LoggingService' })
     private loggingService: LoggingService, // Injecting another service for reuse
@@ -49,6 +49,20 @@ export class ConfigurationService extends BaseService {
 // ...
 ```
 
+### BaseService API
+
+`BaseService` is intentionally minimal. It extends `BaseHelper` to provide scoped logging:
+
+```typescript
+export abstract class BaseService extends BaseHelper implements IService {
+  constructor(opts: { scope: string }) {
+    super({ scope: opts.scope });
+  }
+}
+```
+
+There is no built-in CRUD service -- implement business logic directly in your service methods. This keeps the service layer focused on your domain-specific operations rather than generic data access patterns (which belong in repositories).
+
 ## How Services Fit into the Architecture
 
 Services act as the primary layer for business logic, sitting between controllers and repositories. While controllers are the typical entry point, **services can also inject and call other services**. This enables powerful logic reuse and allows you to build complex use cases by composing smaller, specialized services.
@@ -88,14 +102,14 @@ This layered architecture makes your application:
 ## See Also
 
 - **Related Concepts:**
-  - [Controllers](/guides/core-concepts/controllers) - Call services to handle requests
+  - [Controllers](/guides/core-concepts/rest-controllers) - Call services to handle requests
   - [Repositories](/guides/core-concepts/persistent/repositories) - Data access layer used by services
   - [Dependency Injection](/guides/core-concepts/dependency-injection) - Injecting dependencies into services
 
 - **References:**
   - [BaseService API](/references/base/services) - Complete API reference
   - [Providers](/references/base/providers) - Factory pattern for runtime instantiation
-  - [Logger Helper](/references/helpers/logger/) - Logging in services
+  - [Logger Helper](/extensions/helpers/logger/) - Logging in services
 
 - **Best Practices:**
   - [Architectural Patterns](/best-practices/architectural-patterns) - Service layer design

package/wiki/guides/get-started/5-minute-quickstart.md

@@ -81,7 +81,7 @@ Create `src/index.ts`:
 import { z } from "@hono/zod-openapi";
 import {
   BaseApplication,
-  BaseController,
+  BaseRestController,
   controller,
   get,
   IApplicationInfo,
@@ -94,7 +94,7 @@ import appInfo from "./../package.json";
 
 // 1. Define a controller
 @controller({ path: "/hello" })
-class HelloController extends BaseController {
+class HelloController extends BaseRestController {
   constructor() {
     super({ scope: "HelloController", path: "/hello" });
   }
@@ -108,7 +108,6 @@ class HelloController extends BaseController {
   @get({
     configs: {
       path: "/",
-      method: HTTP.Methods.GET,
       responses: {
         [HTTP.ResultCodes.RS_2.Ok]: jsonContent({
           description: "Says hello",
@@ -235,10 +234,10 @@ Open `http://localhost:3000/doc/explorer` to see interactive Swagger UI document
 
 | Component | What It Does |
 |-----------|--------------|
-| `@controller` | Registers a class as an API controller at `/api/hello` |
-| `@get` | Defines a GET endpoint with OpenAPI metadata |
+| `@controller` | Registers a class as an API controller at `/api/hello`. Supports `transport` field for REST (default) or gRPC |
+| `@get` | Defines a GET endpoint with OpenAPI metadata (auto-sets HTTP method) |
 | `Zod schema` | Validates request/response and auto-generates OpenAPI docs |
-| `BaseController` | Provides lifecycle hooks and route binding capabilities |
+| `BaseRestController` | Provides lifecycle hooks, route binding, and OpenAPI integration for REST controllers |
 | `BaseApplication` | Manages dependency injection, middleware, and server startup |
 | `SwaggerComponent` | Generates interactive API docs at `/doc/explorer` |
 | `app.start()` | Boots the DI container and starts HTTP server on port 3000 |
@@ -296,7 +295,7 @@ You might wonder why we set up TypeScript, ESLint, and Prettier configs in a "qu
   },
 })
 async greet(c: Context) {
-  const { name } = await c.req.json();
+  const { name } = c.req.valid('json');
   return c.json({ greeting: `Hello, ${name}!` }, HTTP.ResultCodes.RS_2.Ok);
 }
 ```

package/wiki/guides/get-started/philosophy.md

@@ -13,7 +13,7 @@ Ignis combines the structured, enterprise-grade development experience of **Loop
 
 ## The Framework Landscape
 
-When building REST APIs with Node.js/Bun, developers choose from three categories of frameworks:
+When building REST APIs and server applications with Node.js/Bun, developers choose from three categories of frameworks:
 
 <div class="landscape-grid">
 

package/wiki/guides/index.md

@@ -1,6 +1,6 @@
 # Getting Started with Ignis
 
-Welcome to Ignis — a TypeScript framework that combines enterprise architecture patterns with Hono's blazing performance. Whether you're building a SaaS backend, REST API, or microservice, these guides will take you from installation to production-ready code with type-safe database operations, auto-generated OpenAPI docs, and clean dependency injection.
+Welcome to Ignis — a TypeScript framework that combines enterprise architecture patterns with Hono's blazing performance. Whether you're building a SaaS backend, REST API, gRPC service, or microservice, these guides will take you from installation to production-ready code with type-safe database operations, auto-generated OpenAPI docs, and clean dependency injection.
 
 <div class="guide-cards">
 
@@ -63,7 +63,7 @@ Welcome to Ignis — a TypeScript framework that combines enterprise architectur
 <span class="stage-num">3</span>
 <h4>Understand the Framework</h4>
 </div>
-<p><a href="./core-concepts/application">Application</a> → <a href="./core-concepts/controllers">Controllers</a> → <a href="./core-concepts/services">Services</a> → <a href="./core-concepts/dependency-injection">DI</a></p>
+<p><a href="./core-concepts/application">Application</a> → <a href="./core-concepts/rest-controllers">Controllers</a> → <a href="./core-concepts/services">Services</a> → <a href="./core-concepts/dependency-injection">DI</a></p>
 <span class="stage-desc">Deep dive into core concepts and architecture patterns</span>
 </div>
 

package/wiki/guides/reference/glossary.md

@@ -8,7 +8,7 @@ Quick reference for key terms in Ignis documentation.
 | Term | Description |
 |------|-------------|
 | **Application** | Main entry point extending `BaseApplication`. Registers all components. |
-| **Controller** | Handles HTTP requests, defines API endpoints (`@controller`, `@get`, `@post`) |
+| **Controller** | Handles HTTP/gRPC requests, defines API endpoints. REST controllers extend `BaseRestController`, gRPC controllers extend `BaseGrpcController`. Uses `@controller`, `@get`, `@post` decorators |
 | **Service** | Contains business logic between controllers and repositories |
 | **Repository** | Database operations for one entity (`find`, `create`, `updateById`, etc.) |
 | **DataSource** | Database connection configuration (host, port, credentials) |
@@ -36,7 +36,7 @@ const TodoRoutes = {
 } as const;
 
 @controller({ path: '/todos' })
-export class TodoController extends BaseController {
+export class TodoController extends BaseRestController {
   @get({ configs: TodoRoutes.GET_ALL })
   async getAll(c: TRouteContext) {
     const todos = await this.repository.find({});
@@ -49,7 +49,7 @@ export class TodoController extends BaseController {
 export class TodoRepository extends DefaultCRUDRepository<typeof Todo.schema> {}
 ```
 
-**Related:** [Application](../core-concepts/application/) | [Controllers](../core-concepts/controllers) | [Services](../core-concepts/services) | [Repositories](../../references/base/repositories/)
+**Related:** [Application](../core-concepts/application/) | [Controllers](../core-concepts/rest-controllers) | [Services](../core-concepts/services) | [Repositories](../../references/base/repositories/)
 
 
 ## TypeScript & Pattern Terms
@@ -59,7 +59,7 @@ Annotations starting with `@` that add behavior to classes/methods.
 
 | Decorator | Purpose |
 |-----------|---------|
-| `@controller` | Marks class as controller |
+| `@controller` | Marks class as controller. Supports `transport` field (`'rest'` default, `'grpc'`) |
 | `@model` | Marks class as model/entity |
 | `@repository` | Marks class as repository |
 | `@datasource` | Marks class as datasource |
@@ -164,7 +164,7 @@ await repository.find({
 | Operator | Meaning | Example |
 |----------|---------|---------|
 | `eq` | Equal | `{ status: { eq: 'active' } }` |
-| `ne` | Not equal | `{ status: { ne: 'deleted' } }` |
+| `neq` | Not equal | `{ status: { neq: 'deleted' } }` |
 | `gt`, `gte` | Greater than (or equal) | `{ age: { gte: 18 } }` |
 | `lt`, `lte` | Less than (or equal) | `{ price: { lt: 100 } }` |
 | `like`, `ilike` | Pattern match | `{ name: { like: '%john%' } }` |
@@ -194,7 +194,7 @@ const TodoRoutes = {
 } as const;
 
 @controller({ path: '/todos' })
-class TodoController {
+class TodoController extends BaseRestController {
   @get({ configs: TodoRoutes.GET_ALL })
   async getAll(c: TRouteContext) { ... }
 
@@ -217,7 +217,7 @@ class TodoController {
 | **Endpoint** | URL path that API responds to (e.g., `GET /todos`) |
 | **Route Parameter** | Variable in URL marked with `:` (e.g., `:id`) |
 | **Request Body** | JSON data sent with POST/PATCH requests |
-| **OpenAPI/Swagger** | Auto-generated API docs at `/docs` |
+| **OpenAPI/Swagger** | Auto-generated API docs at `/doc/explorer` (default path via SwaggerComponent) |
 
 
 ## Environment & Configuration

package/wiki/guides/reference/mcp-docs-server.md

@@ -755,7 +755,7 @@ If this works, the issue is specific to `@venizia/ignis-docs`.
 
 ## What's Next?
 
-- **Learn the Tools:** Read the [Deep Dive Guide](/references/src-details/mcp-server) to understand all 5 available tools
+- **Learn the Tools:** Read the [Deep Dive Guide](/extensions/src-details/mcp-server) to understand all 5 available tools
 - **Advanced Usage:** Explore how to chain tools for complex documentation queries
 - **Contribute:** Help improve the docs or add new features
 

package/wiki/guides/tutorials/building-a-crud-api.md

@@ -598,7 +598,7 @@ this.controller(TodoController);  // ← Make sure this is here!
 path: { base: '/api', isStrict: true },  // All routes start with /api
 ```
 
-**Debug:** Set `debug.showRoutes: true` in appConfigs to see all registered routes on startup.
+**Debug:** Set `debug: { shouldShowRoutes: true }` in appConfigs to see all registered routes on startup.
 
 
 ### Error: "Invalid JSON" when creating todo
@@ -695,7 +695,7 @@ You now have a fully functional CRUD API! Here's what to explore next:
 3. [Components](../core-concepts/components.md) - Build reusable modules
 
 **Add Features:**
-1. [Authentication](/references/components/authentication/) - Add JWT authentication
+1. [Authentication](/extensions/components/authentication/) - Add JWT authentication
 2. [Custom Routes](/best-practices/api-usage-examples.md) - Beyond CRUD operations
 3. [Relationships](../core-concepts/persistent/) - Link todos to users