@venizia/ignis-docs 0.0.7 → 0.0.8-1

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

@@ -6,15 +6,17 @@ Models define your data structure using Drizzle ORM schemas. A model is a single
 
 ```typescript
 // src/models/entities/user.model.ts
-import { BaseEntity, extraUserColumns, generateIdColumnDefs, model } from '@venizia/ignis';
-import { pgTable } from 'drizzle-orm/pg-core';
+import { BaseEntity, generateIdColumnDefs, generateTzColumnDefs, model } from '@venizia/ignis';
+import { pgTable, text } from 'drizzle-orm/pg-core';
 
 @model({ type: 'entity' })
 export class User extends BaseEntity<typeof User.schema> {
   // Define schema as static property
   static override schema = pgTable('User', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
-    ...extraUserColumns({ idType: 'string' }),
+    ...generateTzColumnDefs(),
+    name: text('name').notNull(),
+    email: text('email').notNull(),
   });
 
   // Relations (empty array if none)
@@ -126,7 +128,8 @@ static override schema = pgTable('User', {
 ```typescript
 static override schema = pgTable('User', {
   ...generateIdColumnDefs({ id: { dataType: 'string' } }),  // id (text with UUID default)
-  ...extraUserColumns({ idType: 'string' }),                 // status, audit fields, timestamps
+  ...generateTzColumnDefs(),                                 // createdAt, modifiedAt
+  ...generateUserAuditColumnDefs(),                          // createdBy, modifiedBy
   // ... your fields
 });
 ```
@@ -139,7 +142,6 @@ static override schema = pgTable('User', {
 | `generateTzColumnDefs()` | `createdAt`, `modifiedAt` | Track timestamps |
 | `generateUserAuditColumnDefs()` | `createdBy`, `modifiedBy` | Track who created/updated |
 | `generateDataTypeColumnDefs()` | `dataType`, `tValue`, `nValue`, etc. | Configuration tables |
-| `extraUserColumns()` | Combines audit + status + type | Full-featured entities |
 
 :::note User Audit Options
 The `generateUserAuditColumnDefs` enricher supports an `allowAnonymous` option (default: `true`). Set to `false` to require authenticated user context and throw errors for anonymous operations:
@@ -208,6 +210,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 +268,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

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,40 @@ 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)
+await repo.create({
+  data: { code: 'SETTING', group: 'SYSTEM' },
+  options: { shouldReturn: false },
+});
+
+// Bulk create multiple records
+await repo.createAll({
+  data: [
+    { code: 'SETTING_A', group: 'SYSTEM' },
+    { code: 'SETTING_B', group: 'SYSTEM' },
+  ],
+});
+
+// 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 +209,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 +252,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 +261,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,13 @@ 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]
+> 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.
+
 ## 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 +126,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 +161,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 +182,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',
@@ -220,7 +218,7 @@ this.bindRoute({
 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.controller.ts (Example from @examples/vert)
+// src/controllers/configuration/configuration.controller.ts (Example from @examples/vert)
 import { Configuration } from '@/models';
 import { ConfigurationRepository } from '@/repositories';
 import {
@@ -238,7 +236,7 @@ const _Controller = ControllerFactory.defineCrudController({
   controller: {
     name: 'ConfigurationController',
     basePath: BASE_PATH,
-    isStrict: true,
+    isStrict: { path: true, requestSchema: true },
   },
   entity: () => Configuration, // Provide a resolver for your entity class
 });
@@ -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,11 +15,10 @@ 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';
-import { getError } from '@venizia/ignis-helpers';
 import { ConfigurationRepository } from '../repositories';
 import { UserRepository } from '../repositories';
 import { LoggingService } from './logging.service'; // Example of another service
@@ -27,9 +26,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 +48,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 +101,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