@breadstone/archipel-mcp 0.0.21 → 0.0.23

package/data/patterns/module-pattern.md

@@ -0,0 +1,182 @@
+---
+title: Dynamic Module Pattern
+description: NestJS dynamic modules with register(), port/adapter dependency inversion, and ConfigModule integration.
+order: 6
+---
+
+# Archipel Dynamic Module Pattern
+
+## Overview
+
+Archipel platform libraries use **NestJS dynamic modules** with a `register()` factory
+method and **port/adapter dependency inversion**. Each library defines abstract port
+classes. The consuming application provides concrete implementations at registration time.
+
+This pattern keeps platform libraries free of product-specific logic while allowing
+full customization through dependency injection.
+
+## Pattern Structure
+
+### 1. Abstract Port (Contract)
+
+```typescript
+// contracts/FeatureAccessPort.ts
+
+export abstract class FeatureAccessPort {
+
+  public abstract checkAccess(userId: string, featureKey: string): Promise<IFeatureAccessResult>;
+
+  public abstract recordUsage(userId: string, featureKey: string): Promise<void>;
+
+}
+```
+
+Ports are **abstract classes** (not interfaces) so they can serve as NestJS injection tokens.
+
+### 2. Options Interface
+
+```typescript
+// interfaces/IPaymentModuleOptions.ts
+
+export interface IPaymentModuleOptions {
+  /**
+   * Concrete implementation of the FeatureAccessPort.
+   */
+  featureAccess?: Type<FeatureAccessPort>;
+
+  /**
+   * When true the module is registered globally.
+   */
+  isGlobal?: boolean;
+}
+```
+
+### 3. Dynamic Module with register()
+
+```typescript
+// PaymentModule.ts
+import { ConfigModule } from '@breadstone/archipel-platform-core';
+import { type DynamicModule, Module, type Type } from '@nestjs/common';
+
+@Module({})
+export class PaymentModule {
+
+  public static register(options?: IPaymentModuleOptions): DynamicModule {
+    const providers = [StripeClient, FeatureGuard, FeatureUsageInterceptor];
+
+    if (options?.featureAccess) {
+      providers.push({
+        provide: FeatureAccessPort,
+        useClass: options.featureAccess,
+      } as never);
+    }
+
+    return {
+      global: options?.isGlobal ?? false,
+      module: PaymentModule,
+      imports: [ConfigModule.register('platform-payments', PLATFORM_PAYMENTS_CONFIG_ENTRIES)],
+      providers: providers,
+      exports: [StripeClient, FeatureGuard, FeatureUsageInterceptor],
+    };
+  }
+
+}
+```
+
+### 4. Consumer Registration
+
+```typescript
+// In the consuming application:
+@Module({
+  imports: [
+    PaymentModule.register({
+      featureAccess: MyFeatureAccessAdapter,
+      isGlobal: true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Variants in the Codebase
+
+### Simple: PaymentModule
+
+- 1 optional port (`featureAccess`)
+- Optional `isGlobal` flag
+- Config via `ConfigModule.register()`
+
+### Complex: AuthModule
+
+- 4 required ports (`authSubject`, `mfaSubject`, `sessionPersistence`, `verificationSubject`)
+- 2 optional ports (`socialAuth`, `tokenEnricher`)
+- Conditional strategy registration (social OAuth only when `socialAuth` provided)
+- Imports: PassportModule, JwtModule, MappingModule, EventModule, IdentifierModule
+- Middleware configuration via `configure(consumer)`
+
+### Provider-based: BlobModule
+
+- Uses `forRoot()` instead of `register()` (global by default)
+- Discriminated union for provider selection: `{ kind: 'Vercel' }` or `{ kind: 'Custom', useClass: ... }`
+- Optional persistence ports (`objectPersistence`, `variantPersistence`)
+
+### Infrastructure: DatabaseModule
+
+- Both `forRoot()` (global) and `register()` (scoped) variants
+- Factory provider for PrismaService with extensions
+- Health indicator bootstrapping
+
+### Async: McpModule
+
+- `register(options)` for synchronous configuration
+- `registerAsync({ useFactory, inject })` for async (e.g., reading config at runtime)
+- `registerAsync({ useClass })` for factory class pattern
+- `registerAsync({ useExisting })` for reusing an existing factory
+
+## ConfigModule Integration
+
+Every library module imports `ConfigModule.register()` to declare its configuration
+dependencies:
+
+```typescript
+imports: [ConfigModule.register('platform-payments', PLATFORM_PAYMENTS_CONFIG_ENTRIES)]
+```
+
+This registers typed config keys into the global `ConfigRegistry` for validation
+and discovery.
+
+## MappingModule Integration
+
+Modules that need object mapping import `MappingModule.withProfiles()`:
+
+```typescript
+imports: [MappingModule.withProfiles([SessionMappingProfile])]
+```
+
+## Health Indicator Pattern
+
+Infrastructure modules (Database, Blob) register health indicators:
+
+```typescript
+providers: [
+  BlobHealthIndicator,
+  {
+    provide: 'BLOB_HEALTH_INDICATOR_BOOTSTRAP',
+    useFactory: (orchestrator: HealthOrchestrator, indicator: BlobHealthIndicator) => {
+      orchestrator.registerIndicator(indicator);
+      return true;
+    },
+    inject: [HealthOrchestrator, BlobHealthIndicator],
+  },
+]
+```
+
+## Rules
+
+1. **Ports are abstract classes** — not interfaces — so they work as DI tokens.
+2. **`register()` for stateless config**, `registerAsync()` when config depends on runtime values.
+3. **`forRoot()` for global singletons** (database, blob storage), `register()` for scoped modules.
+4. **Always import ConfigModule.register()** to declare environment dependencies.
+5. **Optional ports use conditional provider registration** (`if (options?.port)`).
+6. **Required ports are listed in the options interface** without optional markers.
+7. **Exports should list concrete services, guards, interceptors** — not internal implementation details.

package/data/patterns/query-pattern.md

@@ -0,0 +1,137 @@
+---
+title: Query Pattern
+description: Repository + Query pattern with IRepositoryQuery, factory functions, transactional queries, and rules.
+order: 7
+---
+
+# Archipel Query Pattern (v1)
+
+## Overview
+
+In Archipel, data access follows the **Repository + Query** pattern. Repositories never expose
+raw Prisma delegate methods to services. Instead, every data operation is wrapped in a
+**query factory function** that returns an `IRepositoryQuery` object. Services call
+`repository.execute(someQuery(...))` — never `repository.findFirst(...)` directly.
+
+## Core Interface
+
+```typescript
+export interface IRepositoryQuery<TDelegate, TResult> {
+  readonly name: string;
+  run(model: TDelegate): Promise<TResult>;
+}
+```
+
+- `TDelegate` — the Prisma delegate type (e.g. `Prisma.UserDelegate`)
+- `TResult` — the query's return type
+- `name` — identifier used for logging and debugging
+
+## Factory Function
+
+```typescript
+import { IRepositoryQuery } from '@breadstone/archipel-platform-database';
+
+export function query<TDelegate, TResult>(
+  name: string,
+  run: (model: TDelegate) => Promise<TResult>,
+): IRepositoryQuery<TDelegate, TResult> {
+  return { name, run };
+}
+```
+
+## Type Extraction
+
+```typescript
+export type QueryResultType<T> = T extends IRepositoryQuery<unknown, infer R> ? R : never;
+```
+
+Use this to derive the result type from a query factory without duplicating types:
+```typescript
+type UserProfileResult = QueryResultType<ReturnType<typeof findUserProfileQuery>>;
+```
+
+## How to Write a Query
+
+### Step 1: Define the query factory function
+
+Each query is a **named function** that returns an `IRepositoryQuery`. The function may accept
+parameters — these become the query's runtime arguments.
+
+```typescript
+import { Prisma } from '@prisma/client';
+import { query } from '@breadstone/archipel-platform-database';
+
+export function findUserByEmailQuery(email: string) {
+  return query<Prisma.UserDelegate, { id: string; email: string; name: string } | null>(
+    'findUserByEmail',
+    (model) =>
+      model.findFirst({
+        where: { email },
+        select: { id: true, email: true, name: true },
+      }),
+  );
+}
+```
+
+### Step 2: Call from a service via repository.execute()
+
+```typescript
+// In the service:
+const user = await this._userRepository.execute(findUserByEmailQuery(email));
+```
+
+### Step 3: Extract result type if needed for mapping
+
+```typescript
+type FindUserByEmailResult = QueryResultType<ReturnType<typeof findUserByEmailQuery>>;
+```
+
+## Transactional Queries
+
+For operations that span multiple models, use `transactionalQuery`:
+
+```typescript
+import { Prisma } from '@prisma/client';
+import { transactionalQuery } from '@breadstone/archipel-platform-database';
+
+export function createOrderWithItemsQuery(data: { userId: string; items: Array<{ productId: string; quantity: number }> }) {
+  return transactionalQuery<{ orderId: string }>(
+    'createOrderWithItems',
+    async (tx: Prisma.TransactionClient) => {
+      const order = await tx.order.create({
+        data: { userId: data.userId },
+        select: { id: true },
+      });
+
+      await tx.orderItem.createMany({
+        data: data.items.map((item) => ({
+          orderId: order.id,
+          productId: item.productId,
+          quantity: item.quantity,
+        })),
+      });
+
+      return { orderId: order.id };
+    },
+  );
+}
+```
+
+Called via:
+```typescript
+const result = await this._orderRepository.executeTransactional(
+  createOrderWithItemsQuery({ userId, items }),
+);
+```
+
+## Rules
+
+1. **Never call Prisma delegate methods directly from services.** Always go through `execute(query)`.
+2. **Always select only the fields you need.** Use `select` — never return full records.
+3. **Query names must be descriptive.** Use the pattern: `verbModelByConditionQuery`
+   (e.g. `findUserByEmailQuery`, `countOrdersByStatusQuery`, `updateUserNameQuery`).
+4. **One query per file** for non-trivial queries. Small related queries may share a file.
+5. **Type the result explicitly.** The second generic parameter of `query()` should be an inline
+   object type or a dedicated interface matching the `select` shape.
+6. **Each query factory is a standalone function** (not a class method). Import `query` from
+   `@breadstone/archipel-platform-database`.

package/data/patterns/repository-pattern.md

@@ -0,0 +1,208 @@
+---
+title: Repository Pattern
+description: RepositoryBase subclasses, DelegateArgs/DelegateReturnTypes helpers, module registration, and service injection.
+order: 8
+---
+
+# Archipel Repository Pattern
+
+## Overview
+
+Every Prisma model gets a dedicated **Repository class** extending `RepositoryBase`.
+Repositories are the ONLY code that touches Prisma delegates. Services never call
+Prisma directly — they call `repository.execute(someQuery(...))` or
+`repository.executeTransactional(someTxQuery(...))`.
+
+## RepositoryBase Signature
+
+```typescript
+import { RepositoryBase } from '@breadstone/archipel-platform-database';
+
+export abstract class RepositoryBase<
+  TDelegate extends Record<RepositoryOperations, (args: any) => Promise<any>>,
+  TArgs extends Record<RepositoryOperations, unknown>,
+  TReturn extends Record<RepositoryOperations, unknown>,
+  TEntity = unknown
+>
+```
+
+### Generic Parameters
+
+| Param | Purpose | Example |
+|-------|---------|---------|
+| `TDelegate` | Prisma delegate type from generated client | `Prisma.UserDelegate` |
+| `TArgs` | Argument shapes for each operation | `Prisma.UserFindManyArgs`, etc. |
+| `TReturn` | Return shapes for each operation | `User`, `User[]`, etc. |
+| `TEntity` | Domain entity interface (optional) | `IUserEntity` |
+
+### Helper Types
+
+```typescript
+import { DelegateArgs, DelegateReturnTypes } from '@breadstone/archipel-platform-database';
+
+// These extract args and return types from a delegate automatically:
+type UserArgs = DelegateArgs<Prisma.UserDelegate>;
+type UserReturns = DelegateReturnTypes<Prisma.UserDelegate>;
+```
+
+## How to Create a Repository
+
+### Step 1: Create the repository class
+
+```typescript
+// repositories/UserRepository.ts
+import { Injectable } from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import {
+  DatabaseService,
+  DelegateArgs,
+  DelegateReturnTypes,
+  RepositoryBase,
+} from '@breadstone/archipel-platform-database';
+
+@Injectable()
+export class UserRepository extends RepositoryBase<
+  Prisma.UserDelegate,
+  DelegateArgs<Prisma.UserDelegate>,
+  DelegateReturnTypes<Prisma.UserDelegate>,
+  IUserEntity
+> {
+
+  // #region Ctor
+
+  public constructor(db: DatabaseService) {
+    super(db, db.client.user);
+  }
+
+  // #endregion
+
+}
+```
+
+The constructor receives `DatabaseService` and passes both the service and the
+Prisma delegate (`db.client.user`) to the base class.
+
+### Step 2: Register as a provider in a module
+
+```typescript
+@Module({
+  imports: [DatabaseModule.register()],
+  providers: [UserRepository, UserService],
+  exports: [UserService],
+})
+export class UserModule {}
+```
+
+### Step 3: Inject into a service
+
+```typescript
+@Injectable()
+export class UserService {
+
+  // #region Fields
+
+  private readonly _userRepository: UserRepository;
+
+  // #endregion
+
+  // #region Ctor
+
+  public constructor(userRepository: UserRepository) {
+    this._userRepository = userRepository;
+  }
+
+  // #endregion
+
+  // #region Methods
+
+  public async findById(id: string): Promise<IUserEntity | null> {
+    return this._userRepository.execute(findUserByIdQuery(id));
+  }
+
+  public async findAll(skip = 0, take = 20): Promise<IUserEntity[]> {
+    return this._userRepository.execute(findAllUsersQuery(skip, take));
+  }
+
+  // #endregion
+
+}
+```
+
+## Key Methods on RepositoryBase
+
+### execute(query)
+
+Primary method for data access. Delegates to a query object.
+
+```typescript
+public execute<TResult>(query: IRepositoryQuery<TDelegate, TResult>): Promise<TResult>
+```
+
+### executeTransactional(query)
+
+For multi-model operations within a transaction.
+
+```typescript
+public executeTransactional<TResult>(query: ITransactionalRepositoryQuery<TResult>): Promise<TResult>
+```
+
+### Direct Methods (for legacy or internal use only)
+
+The base class also exposes `findUnique`, `findMany`, `findFirst`, `create`,
+`createMany`, `update`, `updateMany`, `upsert`, `delete`, `deleteMany`,
+`aggregate`, `count`, `groupBy`, `merge`.
+
+**Important:** New code should use `execute(query)` exclusively.
+Direct method calls are available but violate the query pattern convention.
+
+### findMany with Pagination
+
+```typescript
+// Direct method (legacy)
+const results = await this._repository.findMany(args, { page: 1, perPage: 20 });
+```
+
+## Error Handling
+
+All Prisma errors are caught by the base class `tryCatch` wrapper and re-thrown
+as `RepositoryError`:
+
+- `PrismaClientKnownRequestError` → `RepositoryError` with code `'R_KNOWN'`
+- `PrismaClientUnknownRequestError` → `RepositoryError` with code `'R_UNKNOWN'`
+- Other errors are re-thrown unchanged
+
+The global `RepositoryExceptionFilter` catches `RepositoryError` and returns
+HTTP 500 with a structured envelope.
+
+## Query Integration
+
+Repositories work with query factories from the query pattern:
+
+```typescript
+// queries/findUserByIdQuery.ts
+import { Prisma } from '@prisma/client';
+import { query } from '@breadstone/archipel-platform-database';
+
+export function findUserByIdQuery(id: string) {
+  return query<Prisma.UserDelegate, IUserEntity | null>(
+    'findUserById',
+    (model) => model.findFirst({
+      where: { id },
+      select: { id: true, email: true, name: true, createdAt: true },
+    }),
+  );
+}
+
+// Service usage:
+const user = await this._userRepository.execute(findUserByIdQuery(id));
+```
+
+## Rules
+
+1. **One repository per Prisma model** — e.g. `UserRepository`, `OrderRepository`.
+2. **Constructor receives `DatabaseService`** and passes the delegate via `db.client.<model>`.
+3. **Use `DelegateArgs` and `DelegateReturnTypes`** helper types for the RepositoryBase generics.
+4. **New code uses `execute(query)`** — never direct calls like `repository.findFirst()` from services.
+5. **Register as provider** in the feature module, import `DatabaseModule.register()`.
+6. **Repositories are `@Injectable()`** — they participate in NestJS DI.
+7. **Domain entity interface as fourth generic** (`TEntity`) is optional but recommended.