@breadstone/archipel-mcp 0.0.1

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

@@ -0,0 +1,300 @@
+---
+title: platform-database
+description: Prisma ORM integration with PostgreSQL, repository pattern, query abstraction, and pagination.
+order: 5
+tags: [database, prisma, postgresql, repository, queries, pagination]
+package: '@breadstone/archipel-platform-database'
+---
+
+# platform-database
+
+Prisma ORM integration with PostgreSQL featuring a repository base class, type-safe query pattern, transactional support, and cursor-based pagination.
+
+**Package:** `@breadstone/archipel-platform-database`
+
+## Quick Start
+
+```typescript
+import { Module } from '@nestjs/common';
+import { DatabaseModule } from '@breadstone/archipel-platform-database';
+
+@Module({
+  imports: [
+    // Global registration (recommended)
+    DatabaseModule.forRoot(),
+
+    // Feature-scoped registration
+    DatabaseModule.register(),
+  ],
+})
+export class AppModule {}
+```
+
+---
+
+## Module Configuration
+
+```typescript
+interface IDatabaseModuleConfig {
+    middlewares?: Array<unknown>;  // Future extension point
+}
+
+// Global setup
+DatabaseModule.forRoot(config?: IDatabaseModuleConfig): DynamicModule
+
+// Feature-scoped
+DatabaseModule.register(config?: IDatabaseModuleConfig): DynamicModule
+```
+
+### 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)  |
+
+---
+
+## Repository Pattern
+
+### RepositoryBase
+
+All repositories extend `RepositoryBase`, which provides the `execute()` method for running typed queries.
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { RepositoryBase, DatabaseService } from '@breadstone/archipel-platform-database';
+import type { Prisma } from '@prisma/client';
+
+@Injectable()
+export class OrderRepository extends RepositoryBase<Prisma.OrderDelegate, Prisma.OrderFindManyArgs, unknown> {
+  constructor(database: DatabaseService) {
+    super(database.order, database);
+  }
+}
+```
+
+### Query Pattern
+
+Queries are first-class objects that encapsulate data access logic:
+
+```typescript
+import { query, type IRepositoryQuery } from '@breadstone/archipel-platform-database';
+import type { Prisma } from '@prisma/client';
+
+// Define a query
+export const findOrdersByUser = (userId: string) =>
+  query<Prisma.OrderDelegate, IOrderEntity[]>('findOrdersByUser', async (model) => {
+    return model.findMany({
+      where: { userId },
+      orderBy: { createdAt: 'desc' },
+      select: {
+        id: true,
+        status: true,
+        total: true,
+        createdAt: true,
+      },
+    });
+  });
+
+// Define another query
+export const findOrderById = (orderId: string) =>
+  query<Prisma.OrderDelegate, IOrderEntity | null>('findOrderById', async (model) => {
+    return model.findUnique({
+      where: { id: orderId },
+      include: { items: true },
+    });
+  });
+```
+
+### Executing Queries
+
+```typescript
+@Injectable()
+export class OrderService {
+  constructor(private readonly _orderRepository: OrderRepository) {}
+
+  public async getOrdersByUser(userId: string): Promise<IOrderEntity[]> {
+    return this._orderRepository.execute(findOrdersByUser(userId));
+  }
+
+  public async getOrder(orderId: string): Promise<IOrderEntity | null> {
+    return this._orderRepository.execute(findOrderById(orderId));
+  }
+}
+```
+
+### Transactional Queries
+
+For multi-model writes, use `transactionalQuery`:
+
+```typescript
+import { transactionalQuery } from '@breadstone/archipel-platform-database';
+
+export const createOrderWithItems = (
+  userId: string,
+  items: Array<{ productId: string; quantity: number; price: number }>,
+) =>
+  transactionalQuery<IOrderEntity>('createOrderWithItems', async (tx) => {
+    const order = await tx.order.create({
+      data: {
+        userId,
+        status: 'pending',
+        total: items.reduce((sum, i) => sum + i.price * i.quantity, 0),
+      },
+    });
+
+    await tx.orderItem.createMany({
+      data: items.map((item) => ({
+        orderId: order.id,
+        productId: item.productId,
+        quantity: item.quantity,
+        unitPrice: item.price,
+      })),
+    });
+
+    return order;
+  });
+
+// Execute in a repository
+const order = await this._orderRepository.executeTransactional(createOrderWithItems(userId, items));
+```
+
+---
+
+## Database Services
+
+### PrismaService
+
+Extended `PrismaClient` with Prisma Optimize support:
+
+```typescript
+import { PrismaService } from '@breadstone/archipel-platform-database';
+
+// Typically injected via DatabaseModule, not used directly
+@Injectable()
+export class MyService {
+  constructor(private readonly _prisma: PrismaService) {}
+}
+```
+
+### DatabaseService
+
+High-level database operations extending `PrismaService`:
+
+```typescript
+import { DatabaseService } from '@breadstone/archipel-platform-database';
+
+@Injectable()
+export class TransferService {
+  constructor(private readonly _db: DatabaseService) {}
+
+  public async transfer(fromId: string, toId: string, amount: number): Promise<void> {
+    await this._db.transactionCallback(async (tx) => {
+      await tx.account.update({
+        where: { id: fromId },
+        data: { balance: { decrement: amount } },
+      });
+      await tx.account.update({
+        where: { id: toId },
+        data: { balance: { increment: amount } },
+      });
+    });
+  }
+}
+```
+
+---
+
+## Pagination
+
+Cursor-based pagination utility:
+
+```typescript
+import { paginator, type IPaginatedResult } from '@breadstone/archipel-platform-database';
+
+const paginate = paginator({ perPage: 20 });
+
+@Injectable()
+export class ProductService {
+  constructor(private readonly _prisma: PrismaService) {}
+
+  public async listProducts(page: number): Promise<IPaginatedResult<IProductEntity>> {
+    return paginate<IProductEntity>(
+      this._prisma.product,
+      { where: { isActive: true }, orderBy: { name: 'asc' } },
+      { page, perPage: 20 },
+    );
+  }
+}
+```
+
+### IPaginatedResult
+
+```typescript
+interface IPaginatedResult<T> {
+  data: T[];
+  meta: {
+    total: number; // Total matching records
+    lastPage: number; // Last page number
+    currentPage: number; // Current page
+    perPage: number; // Items per page
+    prev: number | null; // Previous page (null if first)
+    next: number | null; // Next page (null if last)
+  };
+}
+```
+
+---
+
+## Entity Models
+
+Domain entities are defined as interfaces under `models/entities/`. They mirror the Prisma schema and serve as the type contract between repositories and services.
+
+```typescript
+// Property names MUST match Prisma schema exactly
+interface IOrderEntity {
+  readonly id: string;
+  readonly userId: string;
+  readonly status: string;
+  readonly total: number;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+}
+```
+
+### Rules
+
+- Entity properties match Prisma schema property names exactly.
+- Entities are pure data — no methods or business logic.
+- Entities reference only other entity interfaces or primitives.
+- One entity interface per file.
+
+---
+
+## Health Check
+
+```typescript
+import { DatabaseHealthIndicator } from '@breadstone/archipel-platform-database';
+
+// Automatically registered with the HealthOrchestrator
+// Accessible via /health endpoint
+```
+
+---
+
+## 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                 |

package/data/packages/platform-documents/api/Class.BaseDocumentRenderer.md

@@ -0,0 +1,103 @@
+---
+title: 'Abstract Class: BaseDocumentRenderer'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-documents**](../)
+
+---
+
+# Abstract Class: BaseDocumentRenderer
+
+Defined in: [renderer/abstracts/BaseDocumentRenderer.ts:18](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-documents/src/renderer/abstracts/BaseDocumentRenderer.ts#L18)
+
+Base class for document renderers.
+Provides common functionality for template loading, parsing, and image processing.
+
+## Implements
+
+- [`IDocumentRenderer`](Interface.IDocumentRenderer)
+
+## Constructors
+
+### Constructor
+
+```ts
+new BaseDocumentRenderer(
+   options,
+   resourceManager,
+   imageProcessor): BaseDocumentRenderer;
+```
+
+Defined in: [renderer/abstracts/BaseDocumentRenderer.ts:29](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-documents/src/renderer/abstracts/BaseDocumentRenderer.ts#L29)
+
+#### Parameters
+
+| Parameter                  | Type                                                                                                                                      | Description                                                                                                                                                                                                                    |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `options`                  | \{ `debug`: `boolean`; `delimiters`: \{ `end`: `string`; `start`: `string`; \}; `maxImageHeight`: `number`; `maxImageWidth`: `number`; \} | -                                                                                                                                                                                                                              |
+| `options.debug`            | `boolean`                                                                                                                                 | Enable debug logging for document processing pipeline. When enabled, detailed logs will be written for: - Parser strategy selection - Template variable replacements - Data object transformations - Renderer processing steps |
+| `options.delimiters`       | \{ `end`: `string`; `start`: `string`; \}                                                                                                 | Delimiters for template placeholders.                                                                                                                                                                                          |
+| `options.delimiters.end`   | `string`                                                                                                                                  | Ending delimiter. **Default** `']]'`                                                                                                                                                                                           |
+| `options.delimiters.start` | `string`                                                                                                                                  | Starting delimiter. **Default** `'[['`                                                                                                                                                                                         |
+| `options.maxImageHeight`   | `number`                                                                                                                                  | Maximum image height in pixels.                                                                                                                                                                                                |
+| `options.maxImageWidth`    | `number`                                                                                                                                  | Maximum image width in pixels.                                                                                                                                                                                                 |
+| `resourceManager`          | `ResourceManager`                                                                                                                         | -                                                                                                                                                                                                                              |
+| `imageProcessor`           | [`IImageProcessor`](Interface.IImageProcessor)                                                                                            | -                                                                                                                                                                                                                              |
+
+#### Returns
+
+`BaseDocumentRenderer`
+
+## Accessors
+
+### supportedFormats
+
+#### Get Signature
+
+```ts
+get abstract supportedFormats(): readonly DocumentFormat[];
+```
+
+Defined in: [renderer/abstracts/BaseDocumentRenderer.ts:46](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-documents/src/renderer/abstracts/BaseDocumentRenderer.ts#L46)
+
+Supported document formats for this renderer.
+
+##### Returns
+
+readonly [`DocumentFormat`](TypeAlias.DocumentFormat)[]
+
+Supported document formats for this renderer.
+
+#### Implementation of
+
+[`IDocumentRenderer`](Interface.IDocumentRenderer).[`supportedFormats`](Interface.IDocumentRenderer#supportedformats)
+
+## Methods
+
+### render()
+
+```ts
+abstract render(options): Promise<IRenderResult>;
+```
+
+Defined in: [renderer/abstracts/BaseDocumentRenderer.ts:54](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-documents/src/renderer/abstracts/BaseDocumentRenderer.ts#L54)
+
+Render a document from template with provided data.
+
+#### Parameters
+
+| Parameter | Type                                         | Description    |
+| --------- | -------------------------------------------- | -------------- |
+| `options` | [`IRenderOptions`](Interface.IRenderOptions) | Render options |
+
+#### Returns
+
+`Promise`\<[`IRenderResult`](Interface.IRenderResult)\>
+
+Render result with buffer and metadata
+
+#### Implementation of
+
+[`IDocumentRenderer`](Interface.IDocumentRenderer).[`render`](Interface.IDocumentRenderer#render)

package/data/packages/platform-documents/api/Class.DocumentEngine.md

@@ -0,0 +1,85 @@
+---
+title: 'Class: DocumentEngine'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-documents**](../)
+
+---
+
+# Class: DocumentEngine
+
+Defined in: [engine/DocumentEngine.ts:16](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-documents/src/engine/DocumentEngine.ts#L16)
+
+DocumentEngine orchestrates document generation workflow.
+Coordinates resource loading and renderer components.
+
+## Constructors
+
+### Constructor
+
+```ts
+new DocumentEngine(resourceManager, renderers): DocumentEngine;
+```
+
+Defined in: [engine/DocumentEngine.ts:41](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-documents/src/engine/DocumentEngine.ts#L41)
+
+#### Parameters
+
+| Parameter         | Type                                                 |
+| ----------------- | ---------------------------------------------------- |
+| `resourceManager` | `ResourceManager`                                    |
+| `renderers`       | [`IDocumentRenderer`](Interface.IDocumentRenderer)[] |
+
+#### Returns
+
+`DocumentEngine`
+
+## Accessors
+
+### renderers
+
+#### Get Signature
+
+```ts
+get renderers(): ReadonlyMap<string, IDocumentRenderer>;
+```
+
+Defined in: [engine/DocumentEngine.ts:33](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-documents/src/engine/DocumentEngine.ts#L33)
+
+Get available renderers.
+
+##### Returns
+
+`ReadonlyMap`\<`string`, [`IDocumentRenderer`](Interface.IDocumentRenderer)\>
+
+Map of format to renderer
+
+## Methods
+
+### render()
+
+```ts
+render(options): Promise<IRenderResult & {
+  name: string;
+}>;
+```
+
+Defined in: [engine/DocumentEngine.ts:68](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-documents/src/engine/DocumentEngine.ts#L68)
+
+Render a document from template.
+
+#### Parameters
+
+| Parameter | Type                                         | Description    |
+| --------- | -------------------------------------------- | -------------- |
+| `options` | [`IRenderOptions`](Interface.IRenderOptions) | Render options |
+
+#### Returns
+
+`Promise`\<[`IRenderResult`](Interface.IRenderResult) & \{
+`name`: `string`;
+\}\>
+
+Render result with buffer and metadata

package/data/packages/platform-documents/api/Class.DocumentModule.md

@@ -0,0 +1,52 @@
+---
+title: 'Class: DocumentModule'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-documents**](../)
+
+---
+
+# Class: DocumentModule
+
+Defined in: [DocumentModule.ts:62](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-documents/src/DocumentModule.ts#L62)
+
+DocumentModule provides services for document generation and image processing.
+Uses abstract base classes and interfaces for extensibility.
+
+## Constructors
+
+### Constructor
+
+```ts
+new DocumentModule(): DocumentModule;
+```
+
+#### Returns
+
+`DocumentModule`
+
+## Methods
+
+### forRoot()
+
+```ts
+static forRoot(options): DynamicModule;
+```
+
+Defined in: [DocumentModule.ts:72](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-documents/src/DocumentModule.ts#L72)
+
+Configures the module with the specified options.
+
+#### Parameters
+
+| Parameter | Type                                                         | Description                       |
+| --------- | ------------------------------------------------------------ | --------------------------------- |
+| `options` | [`IDocumentModuleOptions`](Interface.IDocumentModuleOptions) | The module configuration options. |
+
+#### Returns
+
+`DynamicModule`
+
+Dynamic module definition

package/data/packages/platform-documents/api/Class.SharpImageProcessor.md

@@ -0,0 +1,136 @@
+---
+title: 'Class: SharpImageProcessor'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-documents**](../)
+
+---
+
+# Class: SharpImageProcessor
+
+Defined in: [processor/SharpImageProcessor.ts:15](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-documents/src/processor/SharpImageProcessor.ts#L15)
+
+Sharp-based image processor.
+Handles image resizing and format conversion.
+
+## Implements
+
+- [`IImageProcessor`](Interface.IImageProcessor)
+
+## Constructors
+
+### Constructor
+
+```ts
+new SharpImageProcessor(options): SharpImageProcessor;
+```
+
+Defined in: [processor/SharpImageProcessor.ts:26](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-documents/src/processor/SharpImageProcessor.ts#L26)
+
+#### Parameters
+
+| Parameter | Type                                                         |
+| --------- | ------------------------------------------------------------ |
+| `options` | [`IDocumentModuleOptions`](Interface.IDocumentModuleOptions) |
+
+#### Returns
+
+`SharpImageProcessor`
+
+## Methods
+
+### process()
+
+```ts
+process(payload): Promise<IImagePayload>;
+```
+
+Defined in: [processor/SharpImageProcessor.ts:43](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-documents/src/processor/SharpImageProcessor.ts#L43)
+
+Process image payload.
+
+#### Parameters
+
+| Parameter | Type                                       | Description   |
+| --------- | ------------------------------------------ | ------------- |
+| `payload` | [`IImagePayload`](Interface.IImagePayload) | Image payload |
+
+#### Returns
+
+`Promise`\<[`IImagePayload`](Interface.IImagePayload)\>
+
+Processed payload
+
+#### Implementation of
+
+[`IImageProcessor`](Interface.IImageProcessor).[`process`](Interface.IImageProcessor#process)
+
+---
+
+### toJpeg()
+
+```ts
+toJpeg(
+   buffer,
+   width?,
+   height?,
+quality?): Promise<Buffer<ArrayBufferLike>>;
+```
+
+Defined in: [processor/SharpImageProcessor.ts:104](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-documents/src/processor/SharpImageProcessor.ts#L104)
+
+Convert to JPEG.
+
+#### Parameters
+
+| Parameter  | Type     | Default value | Description   |
+| ---------- | -------- | ------------- | ------------- |
+| `buffer`   | `Buffer` | `undefined`   | Image buffer  |
+| `width?`   | `number` | `undefined`   | Target width  |
+| `height?`  | `number` | `undefined`   | Target height |
+| `quality?` | `number` | `90`          | JPEG quality  |
+
+#### Returns
+
+`Promise`\<`Buffer`\<`ArrayBufferLike`\>\>
+
+JPEG buffer
+
+#### Implementation of
+
+[`IImageProcessor`](Interface.IImageProcessor).[`toJpeg`](Interface.IImageProcessor#tojpeg)
+
+---
+
+### toPng()
+
+```ts
+toPng(
+   buffer,
+   width?,
+height?): Promise<Buffer<ArrayBufferLike>>;
+```
+
+Defined in: [processor/SharpImageProcessor.ts:75](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-documents/src/processor/SharpImageProcessor.ts#L75)
+
+Convert to PNG.
+
+#### Parameters
+
+| Parameter | Type     | Description   |
+| --------- | -------- | ------------- |
+| `buffer`  | `Buffer` | Image buffer  |
+| `width?`  | `number` | Target width  |
+| `height?` | `number` | Target height |
+
+#### Returns
+
+`Promise`\<`Buffer`\<`ArrayBufferLike`\>\>
+
+PNG buffer
+
+#### Implementation of
+
+[`IImageProcessor`](Interface.IImageProcessor).[`toPng`](Interface.IImageProcessor#topng)