@venizia/ignis-docs 0.0.7 → 0.0.8-1

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

@@ -11,8 +11,8 @@ Build your first Ignis API endpoint in 5 minutes. No database, no complex setup
 ```bash
 mkdir my-app && cd my-app
 bun init -y
-bun add hono @hono/zod-openapi @scalar/hono-api-reference @venizia/ignis
-bun add -d typescript @types/bun @venizia/dev-configs
+bun add hono @hono/zod-openapi @scalar/hono-api-reference @venizia/ignis @venizia/ignis-helpers
+bun add -d typescript @types/bun @venizia/dev-configs eslint prettier tsc-alias
 ```
 
 ## Step 2: Configure Development Tools (30 seconds)
@@ -81,7 +81,7 @@ Create `src/index.ts`:
 import { z } from "@hono/zod-openapi";
 import {
   BaseApplication,
-  BaseController,
+  BaseRestController,
   controller,
   get,
   IApplicationInfo,
@@ -94,21 +94,18 @@ 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" });
   }
 
-  // NOTE: This is a function that must be overridden.
-  override binding() {
-    // Bind dependencies here (if needed)
-    // Extra binding routes with functional way, use `bindRoute` or `defineRoute`
-  }
+  // Override binding() to register custom routes via bindRoute() or defineRoute().
+  // For decorator-based routes (@get, @post), this can be empty.
+  override binding() {}
 
   @get({
     configs: {
       path: "/",
-      method: HTTP.Methods.GET,
       responses: {
         [HTTP.ResultCodes.RS_2.Ok]: jsonContent({
           description: "Says hello",
@@ -153,9 +150,11 @@ const app = new App({
     host: "0.0.0.0",
     port: 3000,
     path: { base: "/api", isStrict: false },
+    debug: { shouldShowRoutes: true }, // Prints all registered routes on startup
   },
 });
 
+// start() runs the full lifecycle: preConfigure → register resources → setupMiddlewares → HTTP server
 app.start();
 ```
 
@@ -178,10 +177,11 @@ Update `package.json` to add build scripts:
     "server:prod": "NODE_ENV=production bun run dist/index.js"
   },
   "dependencies": {
-    "hono": "^4.4.12",
+    "hono": "^4.12.1",
     "@hono/zod-openapi": "latest",
     "@scalar/hono-api-reference": "latest",
-    "@venizia/ignis": "latest"
+    "@venizia/ignis": "latest",
+    "@venizia/ignis-helpers": "latest"
   },
   "devDependencies": {
     "typescript": "^5.5.3",
@@ -235,13 +235,13 @@ 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 |
+| `app.start()` | Runs the full lifecycle (preConfigure → register resources → middlewares) then starts HTTP server on port 3000 |
 
 ### Why Development Configs?
 
@@ -296,7 +296,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

@@ -74,10 +74,10 @@ HTTP Request (GET /api/todos/:id)
 
 ```bash
 # Add database packages
-bun add drizzle-orm drizzle-zod pg lodash
+bun add drizzle-orm drizzle-zod pg
 
 # Add dev dependencies for migrations
-bun add -d drizzle-kit @types/pg @types/lodash
+bun add -d drizzle-kit @types/pg
 ```
 
 ## Step 2: Define the Model
@@ -182,7 +182,6 @@ Create `src/datasources/postgres.datasource.ts`:
 import {
   BaseDataSource,
   datasource,
-  TNodePostgresConnector,
   ValueOrPromise,
 } from '@venizia/ignis';
 import { drizzle } from 'drizzle-orm/node-postgres';
@@ -205,7 +204,7 @@ interface IDSConfigs {
  * 3. Drizzle is initialized with the auto-discovered schema
  */
 @datasource({ driver: 'node-postgres' })
-export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, IDSConfigs> {
+export class PostgresDataSource extends BaseDataSource<IDSConfigs> {
   constructor() {
     super({
       name: PostgresDataSource.name,
@@ -243,7 +242,7 @@ export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, I
 - Schema is auto-discovered from `@repository` decorators - no manual registration needed
 - Uses `getSchema()` for lazy schema resolution (resolves when all models are loaded)
 - Uses environment variables for connection config
-- Implements connection lifecycle methods (`connect()`, `disconnect()`)
+- Implements `configure()` for connection setup and `getConnectionString()` for URL generation
 
 > **Deep Dive:** See [DataSources Reference](/references/base/datasources) for advanced configuration and multiple database support.
 
@@ -306,24 +305,18 @@ Dependency Injection (DI) is a design pattern where objects receive their depend
 
 `ControllerFactory` generates a full CRUD controller with automatic validation and OpenAPI docs.
 
-Create `src/controllers/todo.controller.ts`:
+Create `src/controllers/todo/definitions.ts`:
 
 ```typescript
-// src/controllers/todo.controller.ts
+// src/controllers/todo/definitions.ts
 import { Todo } from '@/models/todo.model';
 import { TodoRepository } from '@/repositories/todo.repository';
-import {
-  BindingKeys,
-  BindingNamespaces,
-  controller,
-  ControllerFactory,
-  inject,
-} from '@venizia/ignis';
+import { ControllerFactory } from '@venizia/ignis';
 
-const BASE_PATH = '/todos';
+export const BASE_PATH = '/todos';
 
-// 1. The factory generates a controller class with all CRUD routes
-const _Controller = ControllerFactory.defineCrudController({
+// The factory generates a controller class with all CRUD routes
+export const _Controller = ControllerFactory.defineCrudController({
   repository: { name: TodoRepository.name },
   controller: {
     name: 'TodoController',
@@ -331,8 +324,17 @@ const _Controller = ControllerFactory.defineCrudController({
   },
   entity: () => Todo, // The entity is used to generate OpenAPI schemas
 });
+```
+
+Create `src/controllers/todo/todo.controller.ts`:
 
-// 2. Extend the generated controller to inject the repository
+```typescript
+// src/controllers/todo/todo.controller.ts
+import { TodoRepository } from '@/repositories/todo.repository';
+import { BindingKeys, BindingNamespaces, controller, inject } from '@venizia/ignis';
+import { BASE_PATH, _Controller } from './definitions';
+
+// Extend the generated controller to inject the repository
 @controller({ path: BASE_PATH })
 export class TodoController extends _Controller {
   constructor(
@@ -349,6 +351,12 @@ export class TodoController extends _Controller {
 }
 ```
 
+Create `src/controllers/todo/index.ts`:
+
+```typescript
+export * from './todo.controller';
+```
+
 **Auto-generated Endpoints:**
 | Method | Path | Description |
 |--------|------|-------------|
@@ -371,13 +379,13 @@ Update `src/application.ts` to register all components:
 ```typescript
 // src/application.ts
 import { BaseApplication, IApplicationConfigs, IApplicationInfo, SwaggerComponent, ValueOrPromise } from '@venizia/ignis';
-import { HelloController } from './controllers/hello.controller';
+import { HelloController } from './controllers/hello';
 import packageJson from '../package.json';
 
 // Import our new components
 import { PostgresDataSource } from './datasources/postgres.datasource';
 import { TodoRepository } from './repositories/todo.repository';
-import { TodoController } from './controllers/todo.controller';
+import { TodoController } from './controllers/todo';
 
 export const appConfigs: IApplicationConfigs = {
   host: process.env.HOST ?? '0.0.0.0',
@@ -413,6 +421,9 @@ export class Application extends BaseApplication {
 }
 ```
 
+> [!IMPORTANT] Registration Order
+> Register in this order: **DataSources → Repositories → Services → Controllers**. DataSources must exist before Repositories that reference them. The framework resolves dependencies during initialization, so registering out of order will cause "Binding not found" errors.
+
 ## Step 7: Run Database Migration
 
 ### Understanding Database Migrations
@@ -462,32 +473,27 @@ Add these scripts to your `package.json`:
 
 ```json
 "scripts": {
-  "migrate:dev": "NODE_ENV=development drizzle-kit migrate --config=src/migration.ts",
-  "generate-migration:dev": "NODE_ENV=development drizzle-kit generate --config=src/migration.ts"
+  "db:push": "NODE_ENV=development drizzle-kit push --config=src/migration.ts",
+  "db:generate": "NODE_ENV=development drizzle-kit generate --config=src/migration.ts",
+  "db:migrate": "NODE_ENV=development drizzle-kit migrate --config=src/migration.ts"
 }
 ```
 
 ### Run the Migration
 
+For development, use `push` — it reads your schema and applies changes directly to the database:
+
 ```bash
-bun run migrate:dev
+bun run db:push
 ```
 
 **What happens when you run this:**
 
 1. **Reads** `src/models/todo.model.ts` to see what your schema looks like
-2. **Generates SQL** to create the `Todo` table
-3. **Connects** to your PostgreSQL database
-4. **Executes** the SQL to create the table
-5. **Saves** migration files to `./migration/` folder (for version control)
+2. **Compares** it against the current database state
+3. **Generates and executes** the SQL to create/update tables
 
-**Expected output:**
-```
-Reading schema...
-Generating migration...
-Executing migration...
-✓ Done!
-```
+> **Production workflow:** Use `db:generate` to create versioned migration files, then `db:migrate` to apply them. This gives you version control and rollback capability. `push` is simpler but skips the migration file step.
 
 **Verify it worked:**
 ```bash
@@ -574,7 +580,7 @@ sudo service postgresql start      # Linux
 
 **Fix:**
 ```bash
-bun run migrate:dev
+bun run db:push
 ```
 
 **Verify the table exists:**
@@ -598,7 +604,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
@@ -629,9 +635,9 @@ Now that you've built the Todo API, try building a **User** feature on your own!
 |:----:|------|
 | 1 | Create `src/models/user.model.ts` |
 | 2 | Create `src/repositories/user.repository.ts` (auto-registers User with PostgresDataSource) |
-| 3 | Create `src/controllers/user.controller.ts` |
+| 3 | Create `src/controllers/user/` (definitions.ts, user.controller.ts, index.ts) |
 | 4 | Register repository and controller in `application.ts` |
-| 5 | Run migration: `bun run migrate:dev` |
+| 5 | Push schema: `bun run db:push` |
 | 6 | Test with curl |
 
 **Hint:** Follow the exact same pattern as `Todo`. The only changes are the model name and fields!
@@ -695,7 +701,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
 

package/wiki/guides/tutorials/complete-installation.md

@@ -19,15 +19,15 @@ bun init -y
 ### Production Dependencies
 
 ```bash
-bun add hono @hono/zod-openapi @scalar/hono-api-reference @venizia/ignis dotenv-flow
+bun add hono @hono/zod-openapi @scalar/hono-api-reference @venizia/ignis @venizia/ignis-helpers
 ```
 
 **What each package does:**
 - `hono` - High-performance web framework
 - `@hono/zod-openapi` - OpenAPI schema generation with Zod validation
 - `@scalar/hono-api-reference` - Interactive API documentation UI
-- `@venizia/ignis` - Core Ignis framework
-- `dotenv-flow` - Environment variable management
+- `@venizia/ignis` - Core Ignis framework (application, controllers, repositories, DI)
+- `@venizia/ignis-helpers` - Utilities (HTTP constants, logger, environment helpers)
 
 ### Development Dependencies
 
@@ -121,7 +121,7 @@ This setup might seem verbose compared to minimal frameworks. The trade-off: ~50
 ### Create Project Structure
 
 ```bash
-mkdir -p src/{common,components,configurations,controllers,datasources,helpers,models/{entities,requests,responses},repositories,services,utilities}
+mkdir -p src/{common,components,configurations,controllers/hello,datasources,helpers,models/{entities,requests,responses},repositories,services,utilities}
 ```
 
 Your structure will look like:
@@ -137,7 +137,10 @@ src/
 │   └── index.ts            # App configuration files
 ├── controllers/
 │   ├── index.ts            # Export all controllers
-│   └── hello.controller.ts
+│   └── hello/
+│       ├── definitions.ts  # Route configs, schemas, constants
+│       ├── hello.controller.ts
+│       └── index.ts        # Barrel export
 ├── datasources/
 │   └── index.ts            # Database connections
 ├── helpers/
@@ -155,6 +158,8 @@ src/
     └── index.ts            # Utility functions
 ```
 
+Each controller gets its own folder: `definitions.ts` for route configs and Zod schemas, the controller file itself, and an `index.ts` barrel export. This keeps things organized as controllers grow with custom routes, validations, and transformations.
+
 > **Note:** For this guide, we only use `controllers/`. Other folders will be used in the [CRUD Tutorial](./building-a-crud-api.md) when you add database support.
 
 ### Create Application Class
@@ -163,7 +168,7 @@ Create `src/application.ts` - this is where you configure and register all your
 
 ```typescript
 import { BaseApplication, IApplicationConfigs, IApplicationInfo, SwaggerComponent, ValueOrPromise } from '@venizia/ignis';
-import { HelloController } from './controllers/hello.controller';
+import { HelloController } from './controllers';
 import packageJson from '../package.json';
 
 // Define application configurations
@@ -239,86 +244,97 @@ export class Application extends BaseApplication {
 
 **Key takeaway:** You'll mostly work in `preConfigure()` when building your app. The other hooks are there when you need them.
 
-**Application Lifecycle Hooks:**
+**Application Lifecycle Hooks (execution order):**
 | Hook | Purpose | Usage |
 |------|---------|-------|
 | `getAppInfo()` | Application metadata | Required - used for API docs |
-| `staticConfigure()` | Static file serving | Optional |
-| `setupMiddlewares()` | Global middlewares | Optional |
-| `preConfigure()` | **Register resources** | **Main hook** - register controllers, services, etc. |
+| `staticConfigure()` | Static file serving | Optional - runs before DI registration |
+| `preConfigure()` | **Register resources** | **Main hook** - register controllers, services, components, etc. |
+| `registerDataSources()` | Configure datasources | Auto - discovers and configures bound datasources |
+| `registerComponents()` | Configure components | Auto - discovers and configures bound components |
+| `registerControllers()` | Configure controllers | Auto - mounts REST/gRPC routes |
 | `postConfigure()` | Post-initialization | Optional - seed data, background jobs |
+| `setupMiddlewares()` | Global middlewares | Optional - runs after `initialize()`, before server starts |
 
 > **Deep Dive:** See [Application Class Reference](../core-concepts/application/) for detailed lifecycle documentation.
 
 ### Create Controller
 
-Create `src/controllers/hello.controller.ts` - controllers handle HTTP requests and return responses:
+Each controller lives in its own folder with separate files for definitions, logic, and exports.
+
+Create `src/controllers/hello/definitions.ts` — route configs and schemas:
 
 ```typescript
-import {
-  BaseController,
-  controller,
-  api,
-  jsonContent,
-} from '@venizia/ignis';
+import { jsonContent } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
 import { z } from '@hono/zod-openapi';
-import { Context } from 'hono';
 
-const BASE_PATH = '/hello';
+export const BASE_PATH = '/hello';
+
+export const helloRouteConfigs = {
+  sayHello: {
+    method: HTTP.Methods.GET,
+    path: '/',
+    responses: {
+      [HTTP.ResultCodes.RS_2.Ok]: jsonContent({
+        description: 'A simple hello message',
+        schema: z.object({ message: z.string() }),
+      }),
+    },
+  },
+} as const;
+```
+
+Create `src/controllers/hello/hello.controller.ts` — the controller class:
+
+```typescript
+import { BaseRestController, controller, api } from '@venizia/ignis';
+import { HTTP } from '@venizia/ignis-helpers';
+import { Context } from 'hono';
+import { BASE_PATH, helloRouteConfigs } from './definitions';
 
-// The @controller decorator registers this class as a controller
 // All routes in this controller will be under /api/hello (remember path.base: '/api')
 @controller({ path: BASE_PATH })
-export class HelloController extends BaseController {
+export class HelloController extends BaseRestController {
   constructor() {
     super({ scope: HelloController.name, path: BASE_PATH });
   }
 
-  // Required: Override binding() to register routes or dependencies
-  override binding() {
-    // Option 1: Use bindRoute() or defineRoute() for programmatic route registration
-    // this.bindRoute({ method: 'get', path: '/programmatic', handler: this.myHandler });
-
-    // Option 2: Use @api decorator on methods (shown below) - recommended
-  }
+  // Override binding() to register custom routes via bindRoute() or defineRoute().
+  // For decorator-based routes (@api, @get, @post), this can be empty.
+  override binding() {}
 
-  // The @api decorator defines a route (prefer @api with method over @get/@post)
-  @api({
-    configs: {
-      method: HTTP.Methods.GET,
-      path: '/',
-      // This 'responses' config does two things:
-      // 1. Generates OpenAPI/Swagger documentation automatically
-      // 2. Validates that your handler returns the correct shape
-      responses: {
-        [HTTP.ResultCodes.RS_2.Ok]: jsonContent({
-          description: 'A simple hello message',
-          schema: z.object({ message: z.string() }),
-        }),
-      },
-    },
-  })
+  @api({ configs: helloRouteConfigs.sayHello })
   sayHello(c: Context) {
     return c.json({ message: 'Hello, World!' }, HTTP.ResultCodes.RS_2.Ok);
   }
-
-  // For authenticated endpoints, add 'authStrategies':
-  // @api({ configs: { method: HTTP.Methods.GET, path: '/secure', authStrategies: [Authentication.STRATEGY_JWT] } })
 }
 ```
 
+Create `src/controllers/hello/index.ts` — barrel export:
+
+```typescript
+export * from './hello.controller';
+```
+
+Create `src/controllers/index.ts` — export all controllers:
+
+```typescript
+export * from './hello';
+```
+
 **Controller Patterns:**
 
 | Pattern | Description |
 |---------|-------------|
+| `definitions.ts` | Route configs, Zod schemas, and constants — keeps controller file clean |
 | `@controller` | Registers the class as a controller with a base path |
-| `@api` | Defines a route with `method` specified (recommended) |
-| `@get`, `@post`, etc. | Shorthand decorators (also work) |
-| `binding()` | Required override — use `bindRoute()` or `defineRoute()` for programmatic routes |
+| `@api` | Defines a route with `method` specified in configs |
+| `@get`, `@post`, etc. | Shorthand decorators that auto-set the HTTP method (recommended) |
+| `binding()` | Override for programmatic routes via `bindRoute()` / `defineRoute()`. Empty for decorator-based routes |
 | Zod schemas | Provide automatic validation and OpenAPI docs |
 
-> **Deep Dive:** See [Controllers Reference](../core-concepts/controllers.md) for advanced routing patterns and validation.
+> **Deep Dive:** See [Controllers Reference](../core-concepts/rest-controllers.md) for advanced routing patterns and validation.
 
 ### Create Entry Point
 
@@ -338,6 +354,10 @@ const main = async () => {
 
   const applicationName = process.env.APP_ENV_APPLICATION_NAME?.toUpperCase() ?? 'My-App';
   logger.info('[main] Getting ready to start up %s Application...', applicationName);
+
+  // start() runs the full lifecycle automatically:
+  // staticConfigure → preConfigure → registerDataSources → registerComponents
+  // → registerControllers → postConfigure → setupMiddlewares → HTTP server
   await application.start();
   return application;
 };
@@ -345,6 +365,9 @@ const main = async () => {
 export default main();
 ```
 
+> [!TIP]
+> `start()` runs the full lifecycle internally. You only need the explicit `init()` → `boot()` → `start()` sequence when using **auto-discovery** (glob-based booters) to discover controllers/repositories from the filesystem. For manual registration (as shown here), `start()` alone is sufficient.
+
 ## 5. Run Your Application
 
 Add common application scripts to your `package.json`: