@venizia/ignis-docs 0.0.8-3 → 0.1.0

package/{wiki → content}/guides/core-concepts/persistent/transactions.md

@@ -1,6 +1,9 @@
 # Transactions
 
-Ignis supports explicit transaction objects that can be passed across multiple services and repositories, allowing for complex, multi-step business logic to be atomic.
+IGNIS supports explicit transaction objects that can be passed across multiple services and repositories, allowing for complex, multi-step business logic to be atomic.
+
+> [!NOTE] PostgreSQL-only capability
+> Real transactions are a **PostgreSQL connector** capability - `BasePostgresDataSource.getCapabilities()` returns `{ transactions: true }` and its `beginTransaction()` opens a real database transaction, as documented below. The typesense connector inherits the engine-neutral `AbstractDataSource` default: calling `beginTransaction()` on it throws a `501 Not Implemented` (`messageCode: 'core.not_supported'`) via the shared `throwNotSupported` utility. See [Connectors](/references/base/connectors) for the capabilities model.
 
 ## Using Transactions
 
@@ -14,8 +17,8 @@ const tx = await userRepo.beginTransaction({
 
 try {
   // 2. Pass transaction to operations
-  // Create user
-  const user = await userRepo.create({
+  // Create user (write methods return a { count, data } envelope)
+  const { data: user } = await userRepo.create({
     data: userData,
     options: { transaction: tx }
   });
@@ -32,29 +35,54 @@ try {
   // 3. Commit the transaction
   await tx.commit();
 } catch (err) {
-  // 4. Rollback on error
-  await tx.rollback();
-  throw err;
+  // 4. Rollback on error. Nest it: rollback() throws if ROLLBACK itself fails, and a bare
+  //    `await tx.rollback()` here would replace `err` with the rollback error.
+  try {
+    await tx.rollback();
+  } catch (rollbackError) {
+    logger.error('Rollback failed | %s', rollbackError);
+  }
+
+  throw err; // the original cause survives
 }
 ```
 
+> [!WARNING] `commit()` and `rollback()` throw on failure
+> `COMMIT` can genuinely fail - a deadlock, a serialization failure under `SERIALIZABLE`, a dropped
+> connection, a deferred constraint firing at commit time. When it does, `commit()` throws rather
+> than resolving, so you never report success on a write that was never persisted. The connection is
+> then destroyed instead of being returned to the pool, because it may still hold an open
+> transaction that the next borrower would inherit.
+>
+> `rollback()` behaves the same way when it is the FIRST verb to fail. One deliberate exception
+> keeps the everyday `catch { await tx.rollback(); throw error; }` pattern safe: calling
+> `rollback()` on a transaction that already ended BY FAILURE (a failed `COMMIT` or a failed prior
+> `ROLLBACK`) is a silent no-op - nothing was committed and the connection is already destroyed, so
+> the rollback's goal is achieved and your original error survives. The nested-try form above is
+> still the safest general pattern, because a FIRST rollback that itself fails does throw.
+>
+> The destroy half is **driver-specific**: node-postgres (`pg`) discards the poisoned connection,
+> but postgres-js has no destroy semantics (`ReservedSql.release()` takes no argument), so under the
+> postgres-js driver the connection returns to the pool anyway. See
+> [Postgres Drivers & Supabase](./postgres-drivers) for the full asymmetry.
+
 ## Transaction Object
 
-The transaction object returned by `beginTransaction()` has the following properties:
+`beginTransaction()` returns an `IDatabaseTransaction` with the following properties:
 
 | Property/Method | Type | Description |
 | :--- | :--- | :--- |
-| `connector` | `TNodePostgresConnector` | A Drizzle connector bound to the transaction's database client |
+| `connector` | `TRelationalConnector<Schema>` | A Drizzle connector bound to the transaction's dedicated connection |
 | `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 |
+| `commit()` | `Promise<void>` | Commit and release the connection. **Throws** if `COMMIT` fails, and destroys the connection rather than pooling it |
+| `rollback()` | `Promise<void>` | Rollback and release the connection. **Throws** if `ROLLBACK` fails, and destroys the connection rather than pooling it |
 
-Calling `commit()` or `rollback()` on an already-ended transaction throws an error.
+Calling `commit()` or `rollback()` on an already-ended transaction throws an error, with one exception: `rollback()` after the transaction ended BY FAILURE is a silent no-op (see the warning above).
 
 ## Isolation Levels
 
-Ignis supports standard PostgreSQL isolation levels:
+IGNIS supports standard PostgreSQL isolation levels:
 
 | Level | Description | Use Case |
 |-------|-------------|----------|
@@ -63,17 +91,17 @@ Ignis supports standard PostgreSQL isolation levels:
 | `SERIALIZABLE` | Strictest level. Emulates serial execution. | Financial transactions, critical data integrity. |
 
 > [!NOTE]
-> Ignis only supports these three levels. `READ UNCOMMITTED` is **not** accepted — PostgreSQL treats it as `READ COMMITTED` anyway, so Ignis omits it to avoid confusion.
+> IGNIS only supports these three levels. The fourth SQL-standard level (uncommitted reads) is **not** accepted - PostgreSQL treats it as `READ COMMITTED` anyway, so IGNIS omits it to avoid confusion.
 
 ## Best Practices
 
-1.  **Always use `try...catch`**: Ensure `rollback()` is called on error to release the connection back to the pool.
+1.  **Always use `try...catch`, and nest the rollback**: `rollback()` throws when `ROLLBACK` fails, so a bare `await tx.rollback()` inside a `catch` would discard the error that sent you there. Wrap it in its own `try...catch`, log the rollback failure, and rethrow the original cause.
 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
 // Service method supporting transactions
-async createInitialOrder(opts: { userId: string; transaction?: ITransaction }) {
+async createInitialOrder(opts: { userId: string; transaction?: IDatabaseTransaction }) {
   return this.orderRepository.create({
     data: { userId: opts.userId, status: 'PENDING' },
     options: { transaction: opts.transaction } // Forward the transaction
@@ -99,12 +127,12 @@ export class OrderService extends BaseService {
   async createOrderWithItems(opts: {
     orderData: TOrderCreate;
     items: TOrderItemCreate[];
-    transaction?: ITransaction;
+    transaction?: IDatabaseTransaction;
   }) {
     const { orderData, items, transaction } = opts;
 
     // Create order
-    const order = await this._orderRepository.create({
+    const { data: order } = await this._orderRepository.create({
       data: orderData,
       options: { transaction },
     });
@@ -138,7 +166,7 @@ export class OrderController extends BaseRestController {
 
   @post({ configs: OrderRoutes.CREATE })
   async createOrder(c: TRouteContext) {
-    const body = c.req.valid<{ order: any; items: any[] }>('json');
+    const body = await c.req.json<{ order: TOrderCreate; items: TOrderItemCreate[] }>();
 
     const tx = await this._orderRepository.beginTransaction({
       isolationLevel: 'SERIALIZABLE',
@@ -154,7 +182,12 @@ export class OrderController extends BaseRestController {
       await tx.commit();
       return c.json(order, HTTP.ResultCodes.RS_2.Created);
     } catch (err) {
-      await tx.rollback();
+      try {
+        await tx.rollback();
+      } catch (rollbackError) {
+        this.logger.error('Rollback failed | %s', rollbackError);
+      }
+
       throw err;
     }
   }
@@ -163,15 +196,18 @@ export class OrderController extends BaseRestController {
 
 ## 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.
+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 dedicated connection) 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;
+// Inside PostgresBaseRepository (simplified)
+protected resolveConnector(opts?: { transaction?: IDatabaseTransaction }) {
+  if (!opts?.transaction) {
+    return this.dataSource.connector;
   }
-  return this.dataSource.connector;
+
+  // Throws if the transaction has already been committed/rolled back,
+  // or if it is not a postgres transaction.
+  return opts.transaction.connector;
 }
 ```
 

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

@@ -1,6 +1,6 @@
 # REST Controllers
 
-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.
+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 [REST Controllers Reference](../../references/base/controllers.md) for the complete API.
 
@@ -9,8 +9,9 @@ REST controllers handle incoming HTTP requests and return JSON responses -- they
 Extend `BaseRestController` and use decorators to define routes:
 
 ```typescript
-import { BaseRestController, controller, get, jsonResponse, z, TRouteContext } from '@venizia/ignis';
+import { BaseRestController, controller, get, jsonResponse, TRouteContext } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
+import { z } from '@hono/zod-openapi';
 
 @controller({ path: '/users' })
 export class UserController extends BaseRestController {
@@ -55,7 +56,7 @@ For decorator-based routes, you do not need to explicitly annotate the return ty
 
 ### HTTP Method Decorators
 
-`Ignis` provides a decorator for each common HTTP method:
+`IGNIS` provides a decorator for each common HTTP method:
 
 -   `@get(opts)`
 -   `@post(opts)`
@@ -132,7 +133,7 @@ export class MyItemsController extends BaseRestController {
 
 ## Manual Route Definition: An Alternative Approach
 
-While decorators are the recommended approach for most use cases, `Ignis` also provides a manual way to define routes within the controller's `binding()` method.
+While decorators are the recommended approach for most use cases, `IGNIS` also provides a manual way to define routes within the controller's `binding()` method.
 
 ### Decorator vs Manual: Quick Comparison
 
@@ -161,8 +162,9 @@ When using this method, you will override the `binding()` method in your control
 Use this method for defining a single API endpoint with all its configurations and handler. It also benefits from type inference when used with `TRouteContext`.
 
 ```typescript
-import { Authentication, jsonResponse, z, TRouteContext } from '@venizia/ignis';
+import { Authentication, jsonResponse, TRouteContext } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
+import { z } from '@hono/zod-openapi';
 
 // ... inside the binding() method
 
@@ -189,8 +191,9 @@ this.defineRoute({
 This method offers a fluent API for defining routes, similar to `defineRoute`, but structured for chaining. It also benefits from `TRouteContext` for type safety.
 
 ```typescript
-import { jsonResponse, z, TRouteContext } from '@venizia/ignis';
+import { jsonResponse, TRouteContext } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
+import { z } from '@hono/zod-openapi';
 
 // ... inside the binding() method
 
@@ -215,7 +218,7 @@ this.bindRoute({
 
 ## `ControllerFactory` for CRUD Operations
 
-For standard CRUD (Create, Read, Update, Delete) operations, `Ignis` provides a `ControllerFactory` that can generate a full-featured controller for any given entity. This significantly reduces boilerplate code.
+For standard CRUD (Create, Read, Update, Delete) operations, `IGNIS` provides a `ControllerFactory` that can generate a full-featured controller for any given entity. This significantly reduces boilerplate code.
 
 ```typescript
 // src/controllers/configuration/configuration.controller.ts (Example from @examples/vert)
@@ -363,7 +366,7 @@ export const MainLayout: FC<PropsWithChildren<MainLayoutProps>> = ({ title, chil
 };
 ```
 
-> **Note:** JSX support in `Ignis` uses Hono's built-in JSX runtime. Make sure your `tsconfig.json` includes the JSX configuration (this is already set up in the framework's base configuration).
+> **Note:** JSX support in `IGNIS` uses Hono's built-in JSX runtime. Make sure your `tsconfig.json` includes the JSX configuration (this is already set up in the framework's base configuration).
 
 ## Accessing Validated Request Data
 
@@ -454,7 +457,7 @@ Using `TRouteContext` provides a typed context object. By using `c.req.valid<T>(
 - **References:**
   - [BaseRestController API](/references/base/controllers) - Complete REST controller API reference
   - [Middlewares](/references/base/middlewares) - Request interceptors
-  - [Swagger Component](/extensions/components/swagger) - Auto-generate API docs
+  - [Swagger Component](/extensions/components/api-reference) - Auto-generate API docs
   - [Schema Utilities](/references/utilities/schema) - Request/response helpers
 
 - **Tutorials:**

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

@@ -0,0 +1,389 @@
+# Services
+
+Services contain your application's business logic, orchestrating data flow and executing use cases.
+
+> **Deep Dive:** See [Services Reference](../../references/base/services.md) for the full API reference.
+
+## The Business Logic Layer
+
+Services sit between controllers and repositories. A controller receives an HTTP request and immediately delegates to a service; the service applies business rules, calls one or more repositories, and returns the result.
+
+Primary responsibilities:
+
+- **Encapsulate business rules** - validation, state-machine transitions, authorization guards, calculations
+- **Coordinate repositories** - fetch related data, combine writes, enforce consistency
+- **Manage transactions** - begin, commit, or roll back across multiple repository calls
+- **Compose services** - inject and call other services to avoid duplicating logic
+
+Controllers stay thin. Repositories stay dumb. Everything in between is a service.
+
+---
+
+## Creating a Service
+
+Extend `BaseService` and call `super({ scope: ClassName.name })` in the constructor:
+
+```typescript
+import { BaseService, inject } from '@venizia/ignis';
+import { getError, HTTP } from '@venizia/ignis-helpers';
+import { UserRepository } from '../repositories';
+
+export class UserService extends BaseService {
+  constructor(
+    @inject({ key: 'repositories.UserRepository' })
+    private userRepository: UserRepository,
+  ) {
+    super({ scope: UserService.name });
+  }
+
+  async getUser(opts: { id: string }) {
+    const user = await this.userRepository.findById({ id: opts.id });
+
+    if (!user) {
+      throw getError({
+        statusCode: HTTP.ResultCodes.RS_4.NotFound,
+        message: 'User not found',
+      });
+    }
+
+    return user;
+  }
+}
+```
+
+**`scope`** is the tag written into every log line produced by this service. Use `ClassName.name` - it's the project convention and avoids string drift when renaming the class.
+
+---
+
+## Registering a Service
+
+Registration is always imperative - call `this.service(ClassName)` inside an application lifecycle method. Do not add `@injectable` to services; `this.service()` handles the binding.
+
+```typescript
+import { BaseApplication } from '@venizia/ignis';
+import { PostgresDataSource } from './datasources';
+import { UserRepository } from './repositories';
+import { UserService } from './services';
+
+export class Application extends BaseApplication {
+  preConfigure(): void {
+    // Register dependencies first, then the service
+    this.dataSource(PostgresDataSource);
+    this.repository(UserRepository);
+    this.service(UserService);   // binds as 'services.UserService'
+  }
+}
+```
+
+`this.service(UserService)` binds the class at the key `services.UserService`. Any other binding that injects `@inject({ key: 'services.UserService' })` resolves an instance from this binding. Service bindings are **transient** by default - each resolution creates a new instance. If your service must be shared (e.g., it holds state), set the scope explicitly: `this.service(UserService).setScope(BindingScopes.SINGLETON)`.
+
+---
+
+## Injecting Dependencies
+
+Use `@inject({ key })` on each constructor parameter. Two equivalent forms:
+
+### Plain string keys (concise)
+
+```typescript
+constructor(
+  @inject({ key: 'repositories.UserRepository' })
+  private userRepository: UserRepository,
+
+  @inject({ key: 'services.NotificationService' })
+  private notificationService: NotificationService,
+) {
+  super({ scope: UserService.name });
+}
+```
+
+### `BindingKeys.build` (refactor-safe)
+
+```typescript
+import { BindingKeys, BindingNamespaces } from '@venizia/ignis';
+
+constructor(
+  @inject({
+    key: BindingKeys.build({
+      namespace: BindingNamespaces.REPOSITORY,  // 'repositories'
+      key: UserRepository.name,                 // 'UserRepository'
+    }),
+  })
+  private userRepository: UserRepository,
+) {
+  super({ scope: UserService.name });
+}
+```
+
+Both produce the same runtime key (`repositories.UserRepository`). `BindingKeys.build` is preferred in larger codebases because a class rename caught by the TypeScript compiler automatically updates the key.
+
+---
+
+## Logging
+
+`BaseService` inherits `this.logger` from `BaseHelper`. Scope log lines to the current method:
+
+```typescript
+async signIn(opts: { username: string }): Promise<string> {
+  this.logger.for('signIn').info('SignIn called | username: %s', opts.username);
+
+  const user = await this.userRepository.findByUsername(opts.username);
+
+  if (!user) {
+    this.logger.for('signIn').warn('User not found | username: %s', opts.username);
+    throw getError({ statusCode: HTTP.ResultCodes.RS_4.Unauthorized, message: 'Invalid credentials' });
+  }
+
+  this.logger.for('signIn').info('SignIn successful | userId: %s', user.id);
+  return await this.generateToken({ userId: user.id });
+}
+```
+
+`this.logger.for('signIn')` adds a `[signIn]` tag to each line without creating a new logger object.
+
+---
+
+## Service-to-Service Composition
+
+Services can inject other services the same way they inject repositories. This is the primary mechanism for logic reuse.
+
+```typescript
+export class RepositoryTestService extends BaseService {
+  constructor(
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.SERVICE,
+        key: CrudTestService.name,
+      }),
+    })
+    private readonly crudTestService: CrudTestService,
+
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.SERVICE,
+        key: TransactionTestService.name,
+      }),
+    })
+    private readonly transactionTestService: TransactionTestService,
+  ) {
+    super({ scope: RepositoryTestService.name });
+  }
+
+  async runAll(): Promise<void> {
+    await this.crudTestService.run();
+    await this.transactionTestService.run();
+  }
+}
+```
+
+Register all participating services in `preConfigure()`:
+
+```typescript
+this.service(CrudTestService);
+this.service(TransactionTestService);
+this.service(RepositoryTestService);
+```
+
+The DI container resolves the dependency graph automatically - registration order within the same lifecycle phase does not matter.
+
+---
+
+## Worked Example: Authentication Service
+
+The following is representative of `examples/vert/src/services/authentication.service.ts`. It shows the complete pattern: multiple injected dependencies, method-scoped logging, error handling, and calling other services.
+
+```typescript
+import { BaseService, IAuthService, inject, JWKSIssuerTokenService, TContext } from '@venizia/ignis';
+import { getError, HTTP } from '@venizia/ignis-helpers';
+import { compare, genSalt, hash } from 'bcrypt';
+import { Env } from 'hono';
+
+export class AuthenticationService
+  extends BaseService
+  implements IAuthService<Env, TSignInRequest, TSignInResponse, ...>
+{
+  constructor(
+    // Inject a repository by string key
+    @inject({ key: 'repositories.UserRepository' })
+    private userRepository: UserRepository,
+
+    // Inject a built-in framework service by string key
+    @inject({ key: 'services.JWKSIssuerTokenService' })
+    private jwksTokenService: JWKSIssuerTokenService,
+  ) {
+    super({ scope: AuthenticationService.name });
+  }
+
+  async signIn(_context: TContext<Env>, opts: TSignInRequest): Promise<TSignInResponse> {
+    this.logger.for('signIn').info('SignIn called | identifier: %j', opts.identifier);
+
+    const user = await this.userRepository.findByUsername(opts.identifier.value);
+
+    if (!user) {
+      throw getError({
+        statusCode: HTTP.ResultCodes.RS_4.Unauthorized,
+        message: 'Invalid credentials',
+      });
+    }
+
+    const isValid = await compare(opts.credential.value, user.password);
+    if (!isValid) {
+      throw getError({
+        statusCode: HTTP.ResultCodes.RS_4.Unauthorized,
+        message: 'Invalid credentials',
+      });
+    }
+
+    const token = await this.jwksTokenService.generate({
+      payload: { userId: user.id, email: user.email },
+    });
+
+    this.logger.for('signIn').info('SignIn successful | userId: %s', user.id);
+    return { token: { value: token, type: 'Bearer' } };
+  }
+
+  async signUp(_context: TContext<Env>, opts: TSignUpRequest): Promise<TSignUpResponse> {
+    this.logger.for('signUp').info('SignUp called | username: %s', opts.username);
+
+    const existing = await this.userRepository.findByUsername(opts.username);
+    if (existing) {
+      throw getError({
+        statusCode: HTTP.ResultCodes.RS_4.Conflict,
+        message: 'Username already exists',
+      });
+    }
+
+    const salt = await genSalt();
+    const hashedPassword = await hash(opts.credential, salt);
+
+    await this.userRepository.create({ data: { username: opts.username, password: hashedPassword } });
+
+    return { message: 'User registered successfully' };
+  }
+}
+```
+
+Registration:
+
+```typescript
+// application.ts
+preConfigure(): void {
+  this.dataSource(PostgresDataSource);
+  this.repository(UserRepository);
+  this.service(AuthenticationService);  // 'services.AuthenticationService'
+}
+```
+
+---
+
+## Transaction Orchestration
+
+Use a datasource reference to begin a transaction, then pass the transaction handle through repository `options`:
+
+```typescript
+export class CheckoutService extends BaseService {
+  constructor(
+    @inject({ key: 'datasources.PostgresDataSource' })
+    private dataSource: PostgresDataSource,
+
+    @inject({ key: 'repositories.OrderRepository' })
+    private orderRepository: OrderRepository,
+
+    @inject({ key: 'repositories.InventoryRepository' })
+    private inventoryRepository: InventoryRepository,
+  ) {
+    super({ scope: CheckoutService.name });
+  }
+
+  async placeOrder(opts: { userId: string; items: OrderItem[] }): Promise<Order> {
+    const log = this.logger.for('placeOrder');
+    const transaction = await this.dataSource.beginTransaction();
+
+    try {
+      const { data: order } = await this.orderRepository.create({
+        data: { userId: opts.userId },
+        options: { transaction },
+      });
+
+      for (const item of opts.items) {
+        await this.inventoryRepository.updateById({
+          id: item.productId,
+          data: { stock: item.quantity },
+          options: { transaction },
+        });
+      }
+
+      await transaction.commit();
+      log.info('Order placed | orderId: %s', order.id);
+      return order;
+    } catch (error) {
+      await transaction.rollback();
+      log.error('Order failed, rolled back | error: %s', error);
+      throw error;
+    }
+  }
+}
+```
+
+Always call `rollback()` in `catch` - an uncommitted transaction holds a database connection until it is released.
+
+---
+
+## Architecture Diagram
+
+```mermaid
+graph LR
+    A[HTTP Request] --> B(Controller)
+    B --> C{Service A}
+    C --> D{Service B}
+    C --> E[Repository A]
+    D --> F[Repository B]
+    E --> G((Database))
+    F --> G
+
+    subgraph "Presentation"
+        B
+    end
+    subgraph "Business Logic"
+        C
+        D
+    end
+    subgraph "Data Access"
+        E
+        F
+    end
+```
+
+Controllers call services. Services call other services and repositories. Repositories call the database. No layer reaches past its immediate neighbor.
+
+---
+
+## Provider vs Service
+
+**Services** contain business logic and are resolved from the DI container (transient scope by default).
+
+**Providers** implement the Factory pattern - their `value(container)` method produces a configured value or instance on demand (mail transport, cache driver, middleware). Use a Provider when you need to select between multiple implementations at runtime.
+
+See [Providers Reference](/references/base/providers) for the full comparison and examples.
+
+---
+
+## See Also
+
+- **Related Concepts:**
+  - [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
+  - [Logger Helper](/extensions/helpers/logger/) - Logging in services
+
+- **Best Practices:**
+  - [Architectural Patterns](/best-practices/architectural-patterns)
+  - [Testing](/guides/tutorials/testing)
+
+- **Tutorials:**
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api)
+  - [E-commerce API](/guides/tutorials/ecommerce-api)