@breadstone/archipel-mcp 0.0.11 → 0.0.13

package/data/guides/database-setup.md

@@ -0,0 +1,546 @@
+---
+title: Database Setup
+description: Set up PostgreSQL access with Prisma, Prisma Accelerate, repositories, queries, transactions, health checks, and error handling.
+order: 5
+---
+
+# Database Setup
+
+This guide covers everything you need to connect a NestJS application to PostgreSQL through `platform-database`: module registration, Prisma Accelerate for connection pooling, writing repositories and queries, transactions, pagination, health checks, and error handling.
+
+If you haven't installed `platform-core` and registered `ConfigModule` yet, read the [Getting Started](/guides/getting-started) guide first.
+
+---
+
+## Overview
+
+`platform-database` provides:
+
+| Capability                | What it does                                                                       |
+| ------------------------- | ---------------------------------------------------------------------------------- |
+| **DatabaseModule**        | Registers Prisma-backed services for DI with optional Accelerate support           |
+| **DatabaseService**       | Extended Prisma client with transaction helpers                                    |
+| **RepositoryBase**        | Abstract base class for typed repositories with built-in error handling            |
+| **Query pattern**         | Reusable, testable query objects executed through repositories                     |
+| **Transactional queries** | Multi-model writes wrapped in Prisma transactions                                  |
+| **Pagination**            | Offset-based pagination with metadata (total, pages, next/prev)                    |
+| **Health indicator**      | Terminus-based database health check, auto-registered with the health orchestrator |
+| **Exception filter**      | Maps `RepositoryError` to HTTP 500 responses                                       |
+
+---
+
+## Installation
+
+```bash
+yarn add @breadstone/archipel-platform-database
+```
+
+`platform-database` depends on `@prisma/client`. Make sure your project has a Prisma schema and a generated client:
+
+```bash
+yarn add prisma @prisma/client
+npx prisma init
+```
+
+---
+
+## Environment Variables
+
+`platform-database` ships its own config keys and a ready-made entries array. Set the relevant variables in your environment:
+
+```env
+DATABASE_URL=postgresql://user:password@localhost:5432/mydb
+```
+
+For Prisma Accelerate (managed connection pooling), add the Accelerate URL from the Prisma Console:
+
+```env
+DB_ACCELERATE_URL=prisma://accelerate.prisma-data.net/?api_key=your-accelerate-api-key
+```
+
+Optional environment variables for Prisma Optimize (query analysis dashboard):
+
+```env
+DB_OPTIMIZE=true
+DB_OPTIMIZE_API_KEY=your-optimize-api-key
+```
+
+All environment variables recognised by `platform-database`:
+
+| Variable              | Description                               | Required            | Default |
+| --------------------- | ----------------------------------------- | ------------------- | ------- |
+| `DATABASE_URL`        | PostgreSQL connection string              | Yes                 | —       |
+| `DB_ACCELERATE_URL`   | Prisma Accelerate proxy URL               | No                  | `''`    |
+| `DB_AUTO_CONNECTION`  | Auto-connect on module init               | No                  | `true`  |
+| `DB_OPTIMIZE`         | Enable Prisma Optimize query analysis     | No                  | `true`  |
+| `DB_OPTIMIZE_API_KEY` | API key for the Prisma Optimize dashboard | If optimize enabled | `''`    |
+
+### Register Config Entries
+
+Use the exported `PLATFORM_DATABASE_CONFIG_ENTRIES` to register all database keys with the `ConfigModule` — no need to define them manually:
+
+```typescript
+// src/app.module.ts
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@breadstone/archipel-platform-core';
+import { DatabaseModule, PLATFORM_DATABASE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-database';
+
+@Module({
+  imports: [ConfigModule.register('database', PLATFORM_DATABASE_CONFIG_ENTRIES), DatabaseModule.register()],
+})
+export class AppModule {}
+```
+
+The `ConfigModule` validates all required keys at startup. If `DATABASE_URL` is missing, the application fails immediately with a clear error.
+
+---
+
+## Module Registration
+
+### Basic Setup (No Accelerate)
+
+For a direct PostgreSQL connection without Accelerate:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@breadstone/archipel-platform-core';
+import { DatabaseModule, PLATFORM_DATABASE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-database';
+
+@Module({
+  imports: [ConfigModule.register('database', PLATFORM_DATABASE_CONFIG_ENTRIES), DatabaseModule.register()],
+})
+export class AppModule {}
+```
+
+### With Prisma Accelerate
+
+Accelerate provides connection pooling, global caching, and query optimization — especially useful in serverless or edge environments where direct database connections are expensive. You can enable it in two ways:
+
+**Option A — Environment variable (recommended)**
+
+Set `DB_ACCELERATE_URL` in your environment. The module reads it automatically via `ConfigService` — no code changes needed:
+
+```env
+DB_ACCELERATE_URL=prisma://accelerate.prisma-data.net/?api_key=your-accelerate-api-key
+```
+
+```typescript
+@Module({
+  imports: [ConfigModule.register('database', PLATFORM_DATABASE_CONFIG_ENTRIES), DatabaseModule.register()],
+})
+export class AppModule {}
+```
+
+**Option B — Module parameter (takes priority)**
+
+Pass `accelerateUrl` explicitly. This overrides the environment variable:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@breadstone/archipel-platform-core';
+import { DatabaseModule, PLATFORM_DATABASE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-database';
+
+@Module({
+  imports: [
+    ConfigModule.register('database', PLATFORM_DATABASE_CONFIG_ENTRIES),
+    DatabaseModule.register({
+      accelerateUrl: 'prisma://accelerate.prisma-data.net/?api_key=...',
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+When an Accelerate URL is present (from either source), the Prisma client connects through the Accelerate proxy instead of directly to PostgreSQL. The `DATABASE_URL` is still required — Prisma uses it for schema generation and migrations. At runtime, all queries go through the Accelerate URL.
+
+> **Resolution order:** module parameter → `DB_ACCELERATE_URL` environment variable → no Accelerate.
+
+### Global Registration with `forRoot`
+
+Use `forRoot()` to make `DatabaseService` globally available without re-importing the module in every feature module:
+
+```typescript
+@Module({
+  imports: [ConfigModule.register('database', PLATFORM_DATABASE_CONFIG_ENTRIES), DatabaseModule.forRoot()],
+})
+export class AppModule {}
+```
+
+With `forRoot()`, any module can inject `DatabaseService` without adding `DatabaseModule` to its own `imports`. Accelerate resolution works the same way — via environment variable or explicit `forRoot({ accelerateUrl: '...' })`.
+
+---
+
+## Defining Entities
+
+Define entity interfaces that map to your Prisma models. Entity property names must match your Prisma schema exactly:
+
+```typescript
+// src/users/models/entities/IUserEntity.ts
+export interface IUserEntity {
+  readonly id: string;
+  readonly userName: string;
+  readonly email: string;
+  readonly createdAt: Date;
+}
+```
+
+Entities are plain interfaces — no methods, no business logic, no mapping. They are the contract between repositories and services.
+
+---
+
+## Writing Queries
+
+Queries are plain objects created with the `query()` factory. Each query receives a Prisma delegate and returns a typed result. This keeps data access logic reusable, testable, and separate from repository class methods.
+
+### Single-Model Query
+
+```typescript
+// src/users/queries/findUserByIdQuery.ts
+import { query, type IRepositoryQuery } from '@breadstone/archipel-platform-database';
+import { type Prisma } from '@prisma/client';
+import { type IUserEntity } from '../models/entities/IUserEntity';
+
+type UserDelegate = Prisma.UserDelegate;
+
+export const findUserByIdQuery = (id: string): IRepositoryQuery<UserDelegate, IUserEntity | null> =>
+  query('findUserById', (model) =>
+    model.findUnique({
+      where: { id },
+      select: { id: true, userName: true, email: true, createdAt: true },
+    }),
+  );
+```
+
+### Transactional Query
+
+When a write spans multiple models, use `transactionalQuery()`. It receives a Prisma `TransactionClient` instead of a single delegate:
+
+```typescript
+// src/orders/queries/createOrderWithItemsQuery.ts
+import { transactionalQuery } from '@breadstone/archipel-platform-database';
+
+export const createOrderWithItemsQuery = (userId: string, items: Array<{ productId: string; quantity: number }>) =>
+  transactionalQuery('createOrderWithItems', async (tx) => {
+    const order = await tx.order.create({
+      data: { userId, status: 'pending' },
+    });
+
+    await tx.orderItem.createMany({
+      data: items.map((item) => ({
+        orderId: order.id,
+        productId: item.productId,
+        quantity: item.quantity,
+      })),
+    });
+
+    return order;
+  });
+```
+
+---
+
+## Creating Repositories
+
+Repositories extend `RepositoryBase` and execute queries. They receive `DatabaseService` and the Prisma delegate via constructor injection.
+
+```typescript
+// src/users/UserRepository.ts
+import { Injectable } from '@nestjs/common';
+import { RepositoryBase, DatabaseService } from '@breadstone/archipel-platform-database';
+import { type Prisma } from '@prisma/client';
+import { findUserByIdQuery } from './queries/findUserByIdQuery';
+import { type IUserEntity } from './models/entities/IUserEntity';
+
+@Injectable()
+export class UserRepository extends RepositoryBase<
+  Prisma.UserDelegate,
+  Prisma.UserArgs,
+  Prisma.UserGetPayload<unknown>,
+  IUserEntity
+> {
+  constructor(db: DatabaseService) {
+    super(db, db.user);
+  }
+
+  public async findById(id: string): Promise<IUserEntity | null> {
+    return this.execute(findUserByIdQuery(id));
+  }
+}
+```
+
+### Executing Transactional Queries
+
+Use `executeTransactional()` for queries that need a transaction client:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { RepositoryBase, DatabaseService } from '@breadstone/archipel-platform-database';
+import { type Prisma } from '@prisma/client';
+import { createOrderWithItemsQuery } from './queries/createOrderWithItemsQuery';
+
+@Injectable()
+export class OrderRepository extends RepositoryBase<
+  Prisma.OrderDelegate,
+  Prisma.OrderArgs,
+  Prisma.OrderGetPayload<unknown>
+> {
+  constructor(db: DatabaseService) {
+    super(db, db.order);
+  }
+
+  public async createWithItems(
+    userId: string,
+    items: Array<{ productId: string; quantity: number }>,
+  ): Promise<unknown> {
+    return this.executeTransactional(createOrderWithItemsQuery(userId, items));
+  }
+}
+```
+
+---
+
+## Pagination
+
+`platform-database` provides offset-based pagination. Pass page options to `findMany()`:
+
+```typescript
+import { type IPaginatedResult } from '@breadstone/archipel-platform-database';
+
+public async listUsers(page: number, perPage: number): Promise<IPaginatedResult<IUserEntity>> {
+  return this.findMany(
+    {
+      select: { id: true, userName: true, email: true, createdAt: true },
+      orderBy: { createdAt: 'desc' },
+    },
+    { page, perPage },
+  );
+}
+```
+
+The result contains:
+
+```typescript
+{
+  data: Array<T>;
+  meta: {
+    total: number;
+    lastPage: number;
+    currentPage: number;
+    perPage: number;
+    prev: number | null;
+    next: number | null;
+  }
+}
+```
+
+---
+
+## Transactions via DatabaseService
+
+For ad-hoc transactions that don't fit the query pattern, use `DatabaseService` directly:
+
+### Batch Transaction
+
+```typescript
+const [user, profile] = await this._db.transaction([
+  this._db.user.create({ data: { userName: 'alice', email: 'alice@example.com' } }),
+  this._db.profile.create({ data: { userId: 'some-id', bio: 'Hello' } }),
+]);
+```
+
+### Callback Transaction
+
+```typescript
+const result = await this._db.transactionCallback(async (tx) => {
+  const user = await tx.user.create({ data: { userName: 'bob', email: 'bob@example.com' } });
+  await tx.profile.create({ data: { userId: user.id, bio: 'Hey there' } });
+  return user;
+});
+```
+
+---
+
+## Health Checks
+
+`DatabaseModule` automatically registers a `DatabaseHealthIndicator` with the health orchestrator from `platform-core`. Once your application exposes a `/health` endpoint, database connectivity is checked via a `SELECT 1` ping. No additional configuration is needed.
+
+If the health check fails, the indicator reports `database: down` with the error details.
+
+---
+
+## Error Handling
+
+### RepositoryError
+
+All Prisma errors caught by `RepositoryBase` are wrapped in `RepositoryError`, which includes the original Prisma error code and metadata:
+
+```typescript
+import { RepositoryError } from '@breadstone/archipel-platform-database';
+
+try {
+  await userRepository.findById('non-existent');
+} catch (error) {
+  if (error instanceof RepositoryError) {
+    console.log(error.code); // 'REPOSITORY_ERROR'
+    console.log(error.originalCode); // e.g. 'P2025' (Prisma error code)
+    console.log(error.meta); // additional error metadata
+  }
+}
+```
+
+### RepositoryExceptionFilter
+
+Register the global exception filter to automatically map `RepositoryError` to HTTP 500 responses:
+
+```typescript
+import { APP_FILTER } from '@nestjs/core';
+import { RepositoryExceptionFilter } from '@breadstone/archipel-platform-database';
+
+@Module({
+  providers: [
+    {
+      provide: APP_FILTER,
+      useClass: RepositoryExceptionFilter,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+The filter returns a consistent error envelope:
+
+```json
+{
+  "statusCode": 500,
+  "timestamp": "2026-04-18T12:00:00.000Z",
+  "error": "Repository Error",
+  "path": "/api/v1/users/123"
+}
+```
+
+---
+
+## Prisma Schema and Migrations
+
+Keep your Prisma schema in your project and use migrations for all schema changes:
+
+```bash
+# Create a new migration after changing schema.prisma
+npx prisma migrate dev --name add-users-table
+
+# Apply migrations in CI/CD
+npx prisma migrate deploy
+
+# Generate the Prisma client after schema changes
+npx prisma generate
+```
+
+> **Important:** Never edit applied migrations. If you need to fix a migration, create a new one.
+
+When using Accelerate, migrations still run against the direct `DATABASE_URL`. Only runtime queries go through the Accelerate proxy.
+
+---
+
+## Full Example
+
+Putting it all together — a complete feature module with database access:
+
+```typescript
+// src/users/UserModule.ts
+import { Module } from '@nestjs/common';
+import { UserRepository } from './UserRepository';
+import { UserService } from './UserService';
+import { UserController } from './UserController';
+
+@Module({
+  providers: [UserRepository, UserService],
+  controllers: [UserController],
+  exports: [UserService],
+})
+export class UserModule {}
+```
+
+```typescript
+// src/users/UserService.ts
+import { Injectable } from '@nestjs/common';
+import { UserRepository } from './UserRepository';
+import { type IUserEntity } from './models/entities/IUserEntity';
+
+@Injectable()
+export class UserService {
+  private readonly _userRepository: UserRepository;
+
+  constructor(userRepository: UserRepository) {
+    this._userRepository = userRepository;
+  }
+
+  public async getUserById(id: string): Promise<IUserEntity | null> {
+    return this._userRepository.findById(id);
+  }
+}
+```
+
+```typescript
+// src/users/UserController.ts
+import { Controller, Get, Param, NotFoundException } from '@nestjs/common';
+import { UserService } from './UserService';
+import { MappingService } from '@breadstone/archipel-platform-core';
+import { USER_TO_RESPONSE } from './mapping-keys';
+
+@Controller('users')
+export class UserController {
+  private readonly _userService: UserService;
+  private readonly _mappingService: MappingService;
+
+  constructor(userService: UserService, mappingService: MappingService) {
+    this._userService = userService;
+    this._mappingService = mappingService;
+  }
+
+  @Get(':id')
+  public async getUser(@Param('id') id: string): Promise<unknown> {
+    const user = await this._userService.getUserById(id);
+    if (!user) {
+      throw new NotFoundException(`User ${id} not found`);
+    }
+
+    return this._mappingService.map(USER_TO_RESPONSE, user);
+  }
+}
+```
+
+And the root module wiring everything together:
+
+```typescript
+// src/app.module.ts
+import { Module } from '@nestjs/common';
+import { ConfigModule, MappingModule } from '@breadstone/archipel-platform-core';
+import { DatabaseModule, PLATFORM_DATABASE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-database';
+import { UserModule } from './users/UserModule';
+
+@Module({
+  imports: [
+    ConfigModule.register('database', PLATFORM_DATABASE_CONFIG_ENTRIES),
+    MappingModule,
+    DatabaseModule.forRoot(),
+    UserModule,
+  ],
+})
+export class AppModule {}
+```
+
+---
+
+## Summary
+
+| Task                    | How                                                                                |
+| ----------------------- | ---------------------------------------------------------------------------------- |
+| Register the module     | `DatabaseModule.register()` or `DatabaseModule.forRoot()` with optional Accelerate |
+| Define entities         | Plain interfaces in `models/entities/`                                             |
+| Write queries           | `query()` for single-model, `transactionalQuery()` for multi-model                 |
+| Create repositories     | Extend `RepositoryBase`, inject `DatabaseService`                                  |
+| Paginate results        | Pass `{ page, perPage }` to `findMany()`                                           |
+| Run transactions        | `executeTransactional()`, `db.transaction()`, or `db.transactionCallback()`        |
+| Monitor database health | Automatic via `DatabaseHealthIndicator`                                            |
+| Handle errors           | `RepositoryExceptionFilter` for HTTP, `RepositoryError` for programmatic handling  |
+| Use Prisma Accelerate   | Set `DB_ACCELERATE_URL` env var or pass `accelerateUrl` in module config           |

package/data/guides/index.md

@@ -27,6 +27,7 @@ Practical guides for working with Archipel packages in your NestJS application.
 
 | Guide                                           | What you'll learn                                                                     |
 | ----------------------------------------------- | ------------------------------------------------------------------------------------- |
+| [Database Setup](./database-setup)              | PostgreSQL via Prisma, Accelerate, repositories, queries, transactions, and health.   |
 | [Blob Storage](./blob-storage)                  | Multi-provider file storage, uploads, signed URLs, and metadata tracking.             |
 | [Document Generation](./document-generation)    | Generate PDF and DOCX from templates with variable substitution and image processing. |
 | [E-Signing Integration](./esigning-integration) | Electronic signature workflows, provider setup, and webhook handling.                 |

package/data/packages/platform-database/api/Class.DatabaseModule.md

@@ -5,9 +5,7 @@ editUrl: false
 ---
 # Class: DatabaseModule
 
-Defined in: [DatabaseModule.ts:48](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/DatabaseModule.ts#L48)
-
-Represents the database module.
+Defined in: [DatabaseModule.ts:62](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/DatabaseModule.ts#L62)
 
 ## Constructors
 
@@ -29,7 +27,7 @@ new DatabaseModule(): DatabaseModule;
 static forRoot(config?): DynamicModule;
 ```
 
-Defined in: [DatabaseModule.ts:57](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/DatabaseModule.ts#L57)
+Defined in: [DatabaseModule.ts:71](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/DatabaseModule.ts#L71)
 
 Registers the `DatabaseModule` with global middlewares.
 
@@ -53,7 +51,7 @@ A `DynamicModule` that can be imported globally
 static register(config?): DynamicModule;
 ```
 
-Defined in: [DatabaseModule.ts:77](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/DatabaseModule.ts#L77)
+Defined in: [DatabaseModule.ts:91](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/DatabaseModule.ts#L91)
 
 Registers the `DatabaseModule` with dynamic middlewares.
 

package/data/packages/platform-database/api/Class.DatabaseService.md

@@ -24,7 +24,7 @@ Represents the database service.
 ### Constructor
 
 ```ts
-new DatabaseService(configService): DatabaseService;
+new DatabaseService(configService, options?): DatabaseService;
 ```
 
 Defined in: [services/DatabaseService.ts:24](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/DatabaseService.ts#L24)
@@ -36,6 +36,7 @@ Constructs a new instance of the `DatabaseService` class.
 | Parameter | Type |
 | ------ | ------ |
 | `configService` | `ConfigService` |
+| `options?` | [`IPrismaServiceOptions`](Interface.IPrismaServiceOptions) |
 
 #### Returns
 
@@ -53,7 +54,7 @@ Constructs a new instance of the `DatabaseService` class.
 onModuleDestroy(): Promise<void>;
 ```
 
-Defined in: [services/PrismaService.ts:80](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L80)
+Defined in: [services/PrismaService.ts:91](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L91)
 
 #### Returns
 
@@ -71,7 +72,7 @@ Defined in: [services/PrismaService.ts:80](https://github.com/RueDeRennes/archip
 onModuleInit(): Promise<void>;
 ```
 
-Defined in: [services/PrismaService.ts:68](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L68)
+Defined in: [services/PrismaService.ts:79](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L79)
 
 #### Returns
 
@@ -149,7 +150,7 @@ Executes a transactional callback (extended overload missing in base typing wrap
 withExtensions(): PrismaService;
 ```
 
-Defined in: [services/PrismaService.ts:44](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L44)
+Defined in: [services/PrismaService.ts:55](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L55)
 
 #### Returns
 

package/data/packages/platform-database/api/Class.PrismaService.md

@@ -5,7 +5,7 @@ editUrl: false
 ---
 # Class: PrismaService
 
-Defined in: [services/PrismaService.ts:20](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L20)
+Defined in: [services/PrismaService.ts:27](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L27)
 
 Represents the prisma service.
 
@@ -33,18 +33,19 @@ Represents the prisma service.
 ### Constructor
 
 ```ts
-new PrismaService(configService): PrismaService;
+new PrismaService(configService, options?): PrismaService;
 ```
 
-Defined in: [services/PrismaService.ts:34](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L34)
+Defined in: [services/PrismaService.ts:41](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L41)
 
-Constructs a new instance of the `DatabaseService` class.
+Constructs a new instance of the `PrismaService` class.
 
 #### Parameters
 
 | Parameter | Type |
 | ------ | ------ |
 | `configService` | `ConfigService` |
+| `options?` | [`IPrismaServiceOptions`](Interface.IPrismaServiceOptions) |
 
 #### Returns
 
@@ -64,7 +65,7 @@ PrismaClient.constructor
 onModuleDestroy(): Promise<void>;
 ```
 
-Defined in: [services/PrismaService.ts:80](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L80)
+Defined in: [services/PrismaService.ts:91](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L91)
 
 #### Returns
 
@@ -84,7 +85,7 @@ OnModuleDestroy.onModuleDestroy
 onModuleInit(): Promise<void>;
 ```
 
-Defined in: [services/PrismaService.ts:68](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L68)
+Defined in: [services/PrismaService.ts:79](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L79)
 
 #### Returns
 
@@ -104,7 +105,7 @@ OnModuleInit.onModuleInit
 withExtensions(): PrismaService;
 ```
 
-Defined in: [services/PrismaService.ts:44](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L44)
+Defined in: [services/PrismaService.ts:55](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L55)
 
 #### Returns
 

package/data/packages/platform-database/api/Interface.IDatabaseModuleConfig.md

@@ -11,12 +11,24 @@ Represents the database module configuration.
 
 ## Properties
 
+### accelerateUrl?
+
+```ts
+optional accelerateUrl?: string;
+```
+
+Defined in: [DatabaseModule.ts:19](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/DatabaseModule.ts#L19)
+
+Prisma Accelerate URL allowing the client to connect through Accelerate.
+
+***
+
 ### middlewares?
 
 ```ts
 optional middlewares?: unknown[];
 ```
 
-Defined in: [DatabaseModule.ts:19](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/DatabaseModule.ts#L19)
+Defined in: [DatabaseModule.ts:21](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/DatabaseModule.ts#L21)
 
 Future extension point for Prisma middlewares

package/data/packages/platform-database/api/Interface.IPrismaServiceOptions.md

@@ -0,0 +1,22 @@
+---
+title: 'Interface: IPrismaServiceOptions'
+generated: true
+editUrl: false
+---
+# Interface: IPrismaServiceOptions
+
+Defined in: [services/PrismaService.ts:16](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L16)
+
+Represents the options for the PrismaService.
+
+## Properties
+
+### accelerateUrl?
+
+```ts
+optional accelerateUrl?: string;
+```
+
+Defined in: [services/PrismaService.ts:18](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L18)
+
+Prisma Accelerate URL allowing the client to connect through Accelerate. Takes priority over the `DB_ACCELERATE_URL` config key.

package/data/packages/platform-database/api/Variable.DATABASE_MODULE_CONFIG.md

@@ -0,0 +1,14 @@
+---
+title: 'Variable: DATABASE\_MODULE\_CONFIG'
+generated: true
+editUrl: false
+---
+# Variable: DATABASE\_MODULE\_CONFIG
+
+```ts
+const DATABASE_MODULE_CONFIG: "DATABASE_MODULE_CONFIG" = 'DATABASE_MODULE_CONFIG';
+```
+
+Defined in: [DatabaseModule.ts:29](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/DatabaseModule.ts#L29)
+
+Represents the database module.

package/data/packages/platform-database/api/Variable.DB_ACCELERATE_URL.md

@@ -0,0 +1,14 @@
+---
+title: 'Variable: DB\_ACCELERATE\_URL'
+generated: true
+editUrl: false
+---
+# Variable: DB\_ACCELERATE\_URL
+
+```ts
+const DB_ACCELERATE_URL: IConfigKey<string>;
+```
+
+Defined in: [configKeys.ts:11](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/configKeys.ts#L11)
+
+Prisma Accelerate URL for managed connection pooling.

package/data/packages/platform-database/api/Variable.DB_AUTO_CONNECTION.md

@@ -0,0 +1,14 @@
+---
+title: 'Variable: DB\_AUTO\_CONNECTION'
+generated: true
+editUrl: false
+---
+# Variable: DB\_AUTO\_CONNECTION
+
+```ts
+const DB_AUTO_CONNECTION: IConfigKey<boolean>;
+```
+
+Defined in: [configKeys.ts:8](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/configKeys.ts#L8)
+
+Whether to skip the automatic database connection on module init.

package/data/packages/platform-database/api/Variable.DB_OPTIMIZE.md

@@ -0,0 +1,14 @@
+---
+title: 'Variable: DB\_OPTIMIZE'
+generated: true
+editUrl: false
+---
+# Variable: DB\_OPTIMIZE
+
+```ts
+const DB_OPTIMIZE: IConfigKey<boolean>;
+```
+
+Defined in: [configKeys.ts:14](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/configKeys.ts#L14)
+
+Whether Prisma Optimize query analysis is enabled.

package/data/packages/platform-database/api/Variable.DB_OPTIMIZE_API_KEY.md

@@ -0,0 +1,14 @@
+---
+title: 'Variable: DB\_OPTIMIZE\_API\_KEY'
+generated: true
+editUrl: false
+---
+# Variable: DB\_OPTIMIZE\_API\_KEY
+
+```ts
+const DB_OPTIMIZE_API_KEY: IConfigKey<string>;
+```
+
+Defined in: [configKeys.ts:17](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/configKeys.ts#L17)
+
+API key for the Prisma Optimize dashboard.

package/data/packages/platform-database/api/Variable.PLATFORM_DATABASE_CONFIG_ENTRIES.md

@@ -0,0 +1,14 @@
+---
+title: 'Variable: PLATFORM\_DATABASE\_CONFIG\_ENTRIES'
+generated: true
+editUrl: false
+---
+# Variable: PLATFORM\_DATABASE\_CONFIG\_ENTRIES
+
+```ts
+const PLATFORM_DATABASE_CONFIG_ENTRIES: ReadonlyArray<Omit<IConfigRegistryEntry, "module">>;
+```
+
+Defined in: [configKeys.ts:20](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/configKeys.ts#L20)
+
+Core configuration entries required by `platform-database`.

package/data/packages/platform-database/api/index.md

@@ -10,7 +10,7 @@ editUrl: false
 | Class | Description |
 | ------ | ------ |
 | [DatabaseHealthIndicator](Class.DatabaseHealthIndicator) | Health indicator for database connectivity. |
-| [DatabaseModule](Class.DatabaseModule) | Represents the database module. |
+| [DatabaseModule](Class.DatabaseModule) | - |
 | [DatabaseService](Class.DatabaseService) | Represents the database service. |
 | [PrismaService](Class.PrismaService) | Represents the prisma service. |
 | [RepositoryBase](Class.RepositoryBase) | The base class for all repositories. |
@@ -23,6 +23,7 @@ editUrl: false
 | [IDatabaseModuleConfig](Interface.IDatabaseModuleConfig) | Represents the database module configuration. |
 | [IPaginatedResult](Interface.IPaginatedResult) | - |
 | [IPaginateOptions](Interface.IPaginateOptions) | - |
+| [IPrismaServiceOptions](Interface.IPrismaServiceOptions) | Represents the options for the PrismaService. |
 | [IRepositoryQuery](Interface.IRepositoryQuery) | Represents a reusable query definition for repositories. |
 | [ITransactionalRepositoryQuery](Interface.ITransactionalRepositoryQuery) | Represents a repository query that requires a Prisma TransactionClient to access multiple delegates. |
 
@@ -36,6 +37,17 @@ editUrl: false
 | [QueryResultType](TypeAlias.QueryResultType) | Extracts the result type from a repository query. Useful for type-safe mapping without duplicating query result types. |
 | [TransactionalQueryResultType](TypeAlias.TransactionalQueryResultType) | Extracts the result type from a transactional repository query. |
 
+## Variables
+
+| Variable | Description |
+| ------ | ------ |
+| [DATABASE\_MODULE\_CONFIG](Variable.DATABASE_MODULE_CONFIG) | Represents the database module. |
+| [DB\_ACCELERATE\_URL](Variable.DB_ACCELERATE_URL) | Prisma Accelerate URL for managed connection pooling. |
+| [DB\_AUTO\_CONNECTION](Variable.DB_AUTO_CONNECTION) | Whether to skip the automatic database connection on module init. |
+| [DB\_OPTIMIZE](Variable.DB_OPTIMIZE) | Whether Prisma Optimize query analysis is enabled. |
+| [DB\_OPTIMIZE\_API\_KEY](Variable.DB_OPTIMIZE_API_KEY) | API key for the Prisma Optimize dashboard. |
+| [PLATFORM\_DATABASE\_CONFIG\_ENTRIES](Variable.PLATFORM_DATABASE_CONFIG_ENTRIES) | Core configuration entries required by `platform-database`. |
+
 ## Functions
 
 | Function | Description |

package/data/packages/platform-database/index.md

@@ -16,10 +16,13 @@ Prisma ORM integration with PostgreSQL featuring a repository base class, type-s
 
 ```typescript
 import { Module } from '@nestjs/common';
-import { DatabaseModule } from '@breadstone/archipel-platform-database';
+import { ConfigModule } from '@breadstone/archipel-platform-core';
+import { DatabaseModule, PLATFORM_DATABASE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-database';
 
 @Module({
   imports: [
+    ConfigModule.register('database', PLATFORM_DATABASE_CONFIG_ENTRIES),
+
     // Global registration (recommended)
     DatabaseModule.forRoot(),
 
@@ -36,6 +39,7 @@ export class AppModule {}
 
 ```typescript
 interface IDatabaseModuleConfig {
+    accelerateUrl?: string;        // Prisma Accelerate URL (overrides DB_ACCELERATE_URL env var)
     middlewares?: Array<unknown>;  // Future extension point
 }
 
@@ -46,14 +50,28 @@ DatabaseModule.forRoot(config?: IDatabaseModuleConfig): DynamicModule
 DatabaseModule.register(config?: IDatabaseModuleConfig): DynamicModule
 ```
 
+### Config Keys
+
+Register all database config keys with `PLATFORM_DATABASE_CONFIG_ENTRIES`:
+
+```typescript
+import { ConfigModule } from '@breadstone/archipel-platform-core';
+import { PLATFORM_DATABASE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-database';
+
+ConfigModule.register('database', PLATFORM_DATABASE_CONFIG_ENTRIES);
+```
+
 ### Environment Variables
 
-| Variable              | Description                      | Required            |
-| --------------------- | -------------------------------- | ------------------- |
-| `DATABASE_URL`        | PostgreSQL connection string     | Yes                 |
-| `DB_OPTIMIZE`         | Enable Prisma query optimization | No                  |
-| `DB_OPTIMIZE_API_KEY` | Prisma Optimize API key          | If optimize enabled |
-| `DB_AUTO_CONNECTION`  | Auto-connect on module init      | No (default: true)  |
+| Variable              | Description                               | Required            | Default |
+| --------------------- | ----------------------------------------- | ------------------- | ------- |
+| `DATABASE_URL`        | PostgreSQL connection string              | Yes                 | —       |
+| `DB_ACCELERATE_URL`   | Prisma Accelerate proxy URL               | No                  | `''`    |
+| `DB_AUTO_CONNECTION`  | Auto-connect on module init               | No                  | `true`  |
+| `DB_OPTIMIZE`         | Enable Prisma Optimize query analysis     | No                  | `true`  |
+| `DB_OPTIMIZE_API_KEY` | API key for the Prisma Optimize dashboard | If optimize enabled | `''`    |
+
+> **Accelerate resolution order:** `accelerateUrl` module parameter → `DB_ACCELERATE_URL` environment variable → no Accelerate.
 
 ---
 
@@ -287,14 +305,19 @@ import { DatabaseHealthIndicator } from '@breadstone/archipel-platform-database'
 
 ## Exports Summary
 
-| Export                    | Type           | Description                              |
-| ------------------------- | -------------- | ---------------------------------------- |
-| `DatabaseModule`          | NestJS Module  | `forRoot()` / `register()`               |
-| `DatabaseService`         | Service        | Extended Prisma client with transactions |
-| `PrismaService`           | Service        | Prisma client with extensions            |
-| `RepositoryBase`          | Abstract class | Base class for repositories              |
-| `query()`                 | Factory        | Create typed query objects               |
-| `transactionalQuery()`    | Factory        | Create transactional query objects       |
-| `paginator()`             | Factory        | Create pagination helper                 |
-| `DatabaseHealthIndicator` | Health         | PostgreSQL health check                  |
-| `DB` (Prisma)             | Namespace      | Re-exported Prisma types                 |
+| Export                             | Type           | Description                              |
+| ---------------------------------- | -------------- | ---------------------------------------- |
+| `DatabaseModule`                   | NestJS Module  | `forRoot()` / `register()`               |
+| `DatabaseService`                  | Service        | Extended Prisma client with transactions |
+| `PrismaService`                    | Service        | Prisma client with extensions            |
+| `RepositoryBase`                   | Abstract class | Base class for repositories              |
+| `query()`                          | Factory        | Create typed query objects               |
+| `transactionalQuery()`             | Factory        | Create transactional query objects       |
+| `paginator()`                      | Factory        | Create pagination helper                 |
+| `DatabaseHealthIndicator`          | Health         | PostgreSQL health check                  |
+| `PLATFORM_DATABASE_CONFIG_ENTRIES` | Constant       | Config entries for `ConfigModule`        |
+| `DB_ACCELERATE_URL`                | Config Key     | Prisma Accelerate URL                    |
+| `DB_AUTO_CONNECTION`               | Config Key     | Auto-connect toggle                      |
+| `DB_OPTIMIZE`                      | Config Key     | Prisma Optimize toggle                   |
+| `DB_OPTIMIZE_API_KEY`              | Config Key     | Prisma Optimize API key                  |
+| `DB` (Prisma)                      | Namespace      | Re-exported Prisma types                 |

package/data/packages/platform-telemetry/api/Class.NoopTelemetryFacade.md

@@ -5,7 +5,7 @@ editUrl: false
 ---
 # Class: NoopTelemetryFacade
 
-Defined in: [core/NoopTelemetryFacade.ts:11](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/NoopTelemetryFacade.ts#L11)
+Defined in: [core/NoopTelemetryFacade.ts:7](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/NoopTelemetryFacade.ts#L7)
 
 ## Implements
 
@@ -31,7 +31,7 @@ new NoopTelemetryFacade(): NoopTelemetryFacade;
 optional recordCacheEvent(_): void;
 ```
 
-Defined in: [core/NoopTelemetryFacade.ts:14](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/NoopTelemetryFacade.ts#L14)
+Defined in: [core/NoopTelemetryFacade.ts:11](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/NoopTelemetryFacade.ts#L11)
 
 #### Parameters
 
@@ -56,21 +56,21 @@ Defined in: [core/NoopTelemetryFacade.ts:14](https://github.com/RueDeRennes/arch
 
 ```ts
 optional recordClientMetric(
-   name, 
-   type, 
-   value, 
+   _name, 
+   _type, 
+   _value, 
    _labels?): void;
 ```
 
-Defined in: [core/NoopTelemetryFacade.ts:19](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/NoopTelemetryFacade.ts#L19)
+Defined in: [core/NoopTelemetryFacade.ts:14](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/NoopTelemetryFacade.ts#L14)
 
 #### Parameters
 
 | Parameter | Type |
 | ------ | ------ |
-| `name` | `string` |
-| `type` | `string` |
-| `value` | `number` |
+| `_name` | `string` |
+| `_type` | `string` |
+| `_value` | `number` |
 | `_labels?` | `Record`\<`string`, `string`\> |
 
 #### Returns
@@ -89,7 +89,7 @@ Defined in: [core/NoopTelemetryFacade.ts:19](https://github.com/RueDeRennes/arch
 runOperation<T>(_, fn): Promise<T>;
 ```
 
-Defined in: [core/NoopTelemetryFacade.ts:13](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/NoopTelemetryFacade.ts#L13)
+Defined in: [core/NoopTelemetryFacade.ts:8](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/NoopTelemetryFacade.ts#L8)
 
 #### Type Parameters
 

package/data/packages/platform-telemetry/api/Interface.ITelemetryFacade.md

@@ -42,7 +42,7 @@ optional recordClientMetric(
    labels?): void;
 ```
 
-Defined in: [core/NoopTelemetryFacade.ts:8](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/NoopTelemetryFacade.ts#L8)
+Defined in: [core/NoopTelemetryFacade.ts:4](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/NoopTelemetryFacade.ts#L4)
 
 #### Parameters
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breadstone/archipel-mcp",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "MCP server providing Archipel platform knowledge — documentation, query patterns, and coding conventions — to AI development tools.",
   "type": "commonjs",
   "main": "./src/main.js",