@breadstone/archipel-mcp 0.0.1

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

@@ -0,0 +1,229 @@
+---
+title: platform-reporting
+description: Business reporting framework with pluggable data contributors and query execution.
+order: 10
+tags: [reporting, analytics, datasets, queries, contributors]
+package: '@breadstone/archipel-platform-reporting'
+---
+
+# platform-reporting
+
+Extensible business reporting framework using a contributor registry pattern. Feature modules register data contributors that expose datasets, and the central facade handles catalog discovery and query execution.
+
+**Package:** `@breadstone/archipel-platform-reporting`
+
+## Quick Start
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ReportingModule } from '@breadstone/archipel-platform-reporting';
+
+@Module({
+  imports: [ReportingModule],
+})
+export class AppModule {}
+```
+
+---
+
+## Contributor Pattern
+
+Each feature module provides an `IReportingContributor` that exposes the datasets it can report on. Contributors are registered with the `ReportingContributorRegistry` and discovered by the `ReportingFacade`.
+
+### IReportingContributor
+
+```typescript
+interface IReportingContributor {
+  readonly featureKey: string;
+  listDatasets(): Promise<IReportingDataset[]>;
+  executeQuery(dataset: IReportingDataset, request: IReportingQuery): Promise<IReportingQueryResult>;
+}
+```
+
+### Implementing a Contributor
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import type {
+  IReportingContributor,
+  IReportingDataset,
+  IReportingQuery,
+  IReportingQueryResult,
+} from '@breadstone/archipel-platform-reporting';
+
+@Injectable()
+export class OrderReportingContributor implements IReportingContributor {
+  public readonly featureKey = 'orders';
+
+  constructor(private readonly _prisma: PrismaService) {}
+
+  public async listDatasets(): Promise<IReportingDataset[]> {
+    return [
+      {
+        datasetId: 'orders.summary',
+        featureKey: 'orders',
+        datasetKey: 'summary',
+        name: 'Order Summary',
+        description: 'Aggregated order data by period',
+        fields: [
+          { fieldId: 'period', label: 'Period', type: 'string', isNullable: false },
+          { fieldId: 'orderCount', label: 'Order Count', type: 'number', isNullable: false },
+          { fieldId: 'revenue', label: 'Revenue', type: 'number', isNullable: false },
+          { fieldId: 'avgOrderValue', label: 'Avg. Order Value', type: 'number', isNullable: false },
+        ],
+      },
+      {
+        datasetId: 'orders.by-product',
+        featureKey: 'orders',
+        datasetKey: 'by-product',
+        name: 'Orders by Product',
+        description: 'Order breakdown by product',
+        fields: [
+          { fieldId: 'productName', label: 'Product', type: 'string', isNullable: false },
+          { fieldId: 'quantity', label: 'Quantity Sold', type: 'number', isNullable: false },
+          { fieldId: 'revenue', label: 'Revenue', type: 'number', isNullable: false },
+        ],
+      },
+    ];
+  }
+
+  public async executeQuery(dataset: IReportingDataset, request: IReportingQuery): Promise<IReportingQueryResult> {
+    // Execute query against database
+    const rows = await this._prisma.$queryRaw`
+            SELECT /* ... */
+        `;
+
+    return {
+      datasetId: dataset.datasetId,
+      fields: dataset.fields,
+      rows,
+      total: rows.length,
+    };
+  }
+}
+```
+
+### Registering a Contributor
+
+```typescript
+import { Module, type OnModuleInit } from '@nestjs/common';
+import { ReportingContributorRegistry } from '@breadstone/archipel-platform-reporting';
+
+@Module({
+  providers: [OrderReportingContributor],
+})
+export class OrderModule implements OnModuleInit {
+  constructor(
+    private readonly _registry: ReportingContributorRegistry,
+    private readonly _contributor: OrderReportingContributor,
+  ) {}
+
+  public onModuleInit(): void {
+    this._registry.register(this._contributor);
+  }
+}
+```
+
+---
+
+## ReportingFacade
+
+Central API for catalog browsing and query execution.
+
+### Browse Catalog
+
+```typescript
+import { ReportingFacade } from '@breadstone/archipel-platform-reporting';
+
+@Controller('api/v1/reports')
+export class ReportController {
+  constructor(private readonly _reporting: ReportingFacade) {}
+
+  @Get('datasets')
+  public async listDatasets(): Promise<IReportingDataset[]> {
+    return this._reporting.getCatalog();
+  }
+
+  @Get('datasets/:id')
+  public async getDataset(@Param('id') id: string): Promise<IReportingDataset> {
+    return this._reporting.getDataset(id);
+  }
+}
+```
+
+### Execute Query
+
+```typescript
+@Post('query')
+public async runQuery(@Body() body: IReportingQuery): Promise<IReportingQueryResult> {
+    return this._reporting.executeQuery(body);
+}
+```
+
+---
+
+## Data Model
+
+### IReportingDataset
+
+```typescript
+interface IReportingDataset {
+  readonly datasetId: string; // e.g. 'orders.summary'
+  readonly featureKey: string; // e.g. 'orders'
+  readonly datasetKey: string; // e.g. 'summary'
+  readonly name: string; // Human-readable name
+  readonly description?: string;
+  readonly fields: IReportingDatasetField[];
+}
+```
+
+### IReportingDatasetField
+
+```typescript
+interface IReportingDatasetField {
+  readonly fieldId: string;
+  readonly label: string;
+  readonly type: ReportingFieldType; // 'boolean' | 'datetime' | 'json' | 'number' | 'string'
+  readonly isNullable: boolean;
+  readonly description?: string;
+}
+```
+
+### IReportingQuery
+
+```typescript
+interface IReportingQuery {
+  readonly datasetId: string;
+  readonly filters?: IReportingQueryFilter[];
+  readonly sorts?: IReportingQuerySort[];
+  readonly limit?: number;
+  readonly offset?: number;
+}
+```
+
+### IReportingQueryResult
+
+```typescript
+interface IReportingQueryResult {
+  readonly datasetId: string;
+  readonly fields: IReportingDatasetField[];
+  readonly rows: ReadonlyArray<Record<string, unknown>>;
+  readonly total: number;
+}
+```
+
+---
+
+## Exports Summary
+
+| Export                          | Type          | Description               |
+| ------------------------------- | ------------- | ------------------------- |
+| `ReportingModule`               | NestJS Module | Global reporting module   |
+| `ReportingFacade`               | Service       | Catalog + query execution |
+| `ReportingContributorRegistry`  | Service       | Contributor registration  |
+| `IReportingContributor`         | Interface     | Contributor contract      |
+| `ReportingDataset`              | Model         | Dataset definition        |
+| `ReportingDatasetField`         | Model         | Field definition          |
+| `ReportingQuery`                | Model         | Query structure           |
+| `ReportingQueryResult`          | Model         | Query result              |
+| `ReportingDatasetNotFoundError` | Error         | Dataset lookup failure    |

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

@@ -0,0 +1,118 @@
+---
+title: 'Class: NoopTelemetryFacade'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-telemetry**](../)
+
+---
+
+# Class: NoopTelemetryFacade
+
+Defined in: [core/NoopTelemetryFacade.ts:11](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/NoopTelemetryFacade.ts#L11)
+
+## Implements
+
+- [`ITelemetryFacade`](Interface.ITelemetryFacade)
+
+## Constructors
+
+### Constructor
+
+```ts
+new NoopTelemetryFacade(): NoopTelemetryFacade;
+```
+
+#### Returns
+
+`NoopTelemetryFacade`
+
+## Methods
+
+### recordCacheEvent()?
+
+```ts
+optional recordCacheEvent(_): void;
+```
+
+Defined in: [core/NoopTelemetryFacade.ts:14](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/NoopTelemetryFacade.ts#L14)
+
+#### Parameters
+
+| Parameter   | Type                                                              |
+| ----------- | ----------------------------------------------------------------- |
+| `_`         | \{ `cache`: `string`; `outcome`: `string`; `phase?`: `string`; \} |
+| `_.cache`   | `string`                                                          |
+| `_.outcome` | `string`                                                          |
+| `_.phase?`  | `string`                                                          |
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+[`ITelemetryFacade`](Interface.ITelemetryFacade).[`recordCacheEvent`](Interface.ITelemetryFacade#recordcacheevent)
+
+---
+
+### recordClientMetric()?
+
+```ts
+optional recordClientMetric(
+   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)
+
+#### Parameters
+
+| Parameter  | Type                           |
+| ---------- | ------------------------------ |
+| `name`     | `string`                       |
+| `type`     | `string`                       |
+| `value`    | `number`                       |
+| `_labels?` | `Record`\<`string`, `string`\> |
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+[`ITelemetryFacade`](Interface.ITelemetryFacade).[`recordClientMetric`](Interface.ITelemetryFacade#recordclientmetric)
+
+---
+
+### runOperation()
+
+```ts
+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)
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+#### Parameters
+
+| Parameter | Type                          |
+| --------- | ----------------------------- |
+| `_`       | `string`                      |
+| `fn`      | () => `T` \| `Promise`\<`T`\> |
+
+#### Returns
+
+`Promise`\<`T`\>
+
+#### Implementation of
+
+[`ITelemetryFacade`](Interface.ITelemetryFacade).[`runOperation`](Interface.ITelemetryFacade#runoperation)

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

@@ -0,0 +1,180 @@
+---
+title: 'Class: TelemetryCacheMetricsRecorder'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-telemetry**](../)
+
+---
+
+# Class: TelemetryCacheMetricsRecorder
+
+Defined in: [core/TelemetryCacheMetricsRecorder.ts:15](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/TelemetryCacheMetricsRecorder.ts#L15)
+
+Generic cache metrics recorder that forwards cache lifecycle events
+into the telemetry facade (which may be a noop when disabled).
+
+## Implements
+
+- `ICacheMetricsRecorder`
+
+## Constructors
+
+### Constructor
+
+```ts
+new TelemetryCacheMetricsRecorder(telemetry): TelemetryCacheMetricsRecorder;
+```
+
+Defined in: [core/TelemetryCacheMetricsRecorder.ts:21](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/TelemetryCacheMetricsRecorder.ts#L21)
+
+#### Parameters
+
+| Parameter   | Type                                             |
+| ----------- | ------------------------------------------------ |
+| `telemetry` | [`ITelemetryFacade`](Interface.ITelemetryFacade) |
+
+#### Returns
+
+`TelemetryCacheMetricsRecorder`
+
+## Methods
+
+### recordEviction()
+
+```ts
+recordEviction(cache): void;
+```
+
+Defined in: [core/TelemetryCacheMetricsRecorder.ts:53](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/TelemetryCacheMetricsRecorder.ts#L53)
+
+Records a cache eviction.
+
+#### Parameters
+
+| Parameter | Type     | Description          |
+| --------- | -------- | -------------------- |
+| `cache`   | `string` | The cache name/label |
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+```ts
+ICacheMetricsRecorder.recordEviction;
+```
+
+---
+
+### recordHit()
+
+```ts
+recordHit(cache): void;
+```
+
+Defined in: [core/TelemetryCacheMetricsRecorder.ts:27](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/TelemetryCacheMetricsRecorder.ts#L27)
+
+Records a cache hit.
+
+#### Parameters
+
+| Parameter | Type     | Description          |
+| --------- | -------- | -------------------- |
+| `cache`   | `string` | The cache name/label |
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+```ts
+ICacheMetricsRecorder.recordHit;
+```
+
+---
+
+### recordLoadError()
+
+```ts
+recordLoadError(cache): void;
+```
+
+Defined in: [core/TelemetryCacheMetricsRecorder.ts:46](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/TelemetryCacheMetricsRecorder.ts#L46)
+
+Records a failed cache load.
+
+#### Parameters
+
+| Parameter | Type     | Description          |
+| --------- | -------- | -------------------- |
+| `cache`   | `string` | The cache name/label |
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+```ts
+ICacheMetricsRecorder.recordLoadError;
+```
+
+---
+
+### recordLoadSuccess()
+
+```ts
+recordLoadSuccess(cache): void;
+```
+
+Defined in: [core/TelemetryCacheMetricsRecorder.ts:39](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/TelemetryCacheMetricsRecorder.ts#L39)
+
+Records a successful cache load.
+
+#### Parameters
+
+| Parameter | Type     | Description          |
+| --------- | -------- | -------------------- |
+| `cache`   | `string` | The cache name/label |
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+```ts
+ICacheMetricsRecorder.recordLoadSuccess;
+```
+
+---
+
+### recordMiss()
+
+```ts
+recordMiss(cache): void;
+```
+
+Defined in: [core/TelemetryCacheMetricsRecorder.ts:33](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/TelemetryCacheMetricsRecorder.ts#L33)
+
+Records a cache miss.
+
+#### Parameters
+
+| Parameter | Type     | Description          |
+| --------- | -------- | -------------------- |
+| `cache`   | `string` | The cache name/label |
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+```ts
+ICacheMetricsRecorder.recordMiss;
+```

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

@@ -0,0 +1,132 @@
+---
+title: 'Class: TelemetryFacade'
+generated: true
+editUrl: false
+---
+
+[**@breadstone/archipel-platform-telemetry**](../)
+
+---
+
+# Class: TelemetryFacade
+
+Defined in: [core/TelemetryFacade.ts:3](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/TelemetryFacade.ts#L3)
+
+## Implements
+
+- [`ITelemetryFacade`](Interface.ITelemetryFacade)
+
+## Constructors
+
+### Constructor
+
+```ts
+new TelemetryFacade(): TelemetryFacade;
+```
+
+#### Returns
+
+`TelemetryFacade`
+
+## Methods
+
+### getLogger()
+
+```ts
+getLogger(): Logger;
+```
+
+Defined in: [core/TelemetryFacade.ts:45](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/TelemetryFacade.ts#L45)
+
+#### Returns
+
+`Logger`
+
+---
+
+### recordCacheEvent()
+
+```ts
+recordCacheEvent(event): void;
+```
+
+Defined in: [core/TelemetryFacade.ts:25](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/TelemetryFacade.ts#L25)
+
+#### Parameters
+
+| Parameter       | Type                                                              |
+| --------------- | ----------------------------------------------------------------- |
+| `event`         | \{ `cache`: `string`; `outcome`: `string`; `phase?`: `string`; \} |
+| `event.cache`   | `string`                                                          |
+| `event.outcome` | `string`                                                          |
+| `event.phase?`  | `string`                                                          |
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+[`ITelemetryFacade`](Interface.ITelemetryFacade).[`recordCacheEvent`](Interface.ITelemetryFacade#recordcacheevent)
+
+---
+
+### recordClientMetric()
+
+```ts
+recordClientMetric(
+   name,
+   type,
+   value,
+   labels?): void;
+```
+
+Defined in: [core/TelemetryFacade.ts:35](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/TelemetryFacade.ts#L35)
+
+#### Parameters
+
+| Parameter | Type                           |
+| --------- | ------------------------------ |
+| `name`    | `string`                       |
+| `type`    | `string`                       |
+| `value`   | `number`                       |
+| `labels?` | `Record`\<`string`, `string`\> |
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+[`ITelemetryFacade`](Interface.ITelemetryFacade).[`recordClientMetric`](Interface.ITelemetryFacade#recordclientmetric)
+
+---
+
+### runOperation()
+
+```ts
+runOperation<T>(name, fn): Promise<T>;
+```
+
+Defined in: [core/TelemetryFacade.ts:7](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/core/TelemetryFacade.ts#L7)
+
+#### Type Parameters
+
+| Type Parameter |
+| -------------- |
+| `T`            |
+
+#### Parameters
+
+| Parameter | Type                          |
+| --------- | ----------------------------- |
+| `name`    | `string`                      |
+| `fn`      | () => `T` \| `Promise`\<`T`\> |
+
+#### Returns
+
+`Promise`\<`T`\>
+
+#### Implementation of
+
+[`ITelemetryFacade`](Interface.ITelemetryFacade).[`runOperation`](Interface.ITelemetryFacade#runoperation)