feat: foundation — Docker Compose, OTEL, shared types (#65)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

.env.example

@@ -0,0 +1,12 @@
+# Database
+DATABASE_URL=postgresql://mosaic:mosaic@localhost:5432/mosaic
+
+# Valkey (Redis-compatible)
+VALKEY_URL=redis://localhost:6379
+
+# OpenTelemetry
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+OTEL_SERVICE_NAME=mosaic-gateway
+
+# Gateway
+GATEWAY_PORT=4000

apps/gateway/package.json

@@ -12,12 +12,19 @@
     "test": "vitest run"
   },
   "dependencies": {
+    "@mariozechner/pi-coding-agent": "~0.57.1",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "@nestjs/platform-fastify": "^11.0.0",
     "@nestjs/platform-socket.io": "^11.0.0",
     "@nestjs/websockets": "^11.0.0",
-    "@mariozechner/pi-coding-agent": "~0.57.1",
+    "@opentelemetry/auto-instrumentations-node": "^0.71.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.213.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.213.0",
+    "@opentelemetry/resources": "^2.6.0",
+    "@opentelemetry/sdk-metrics": "^2.6.0",
+    "@opentelemetry/sdk-node": "^0.213.0",
+    "@opentelemetry/semantic-conventions": "^1.40.0",
     "fastify": "^5.0.0",
     "reflect-metadata": "^0.2.0",
     "rxjs": "^7.8.0",

apps/gateway/src/main.ts

@@ -1,16 +1,21 @@
+import './tracing.js';
 import 'reflect-metadata';
 import { NestFactory } from '@nestjs/core';
+import { Logger } from '@nestjs/common';
 import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
 import { AppModule } from './app.module.js';
 
 async function bootstrap(): Promise<void> {
+  const logger = new Logger('Bootstrap');
   const app = await NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter());
 
-  await app.listen(4000, '0.0.0.0');
+  const port = process.env['GATEWAY_PORT'] ?? 4000;
-  console.log('Gateway listening on port 4000');
+  await app.listen(port as number, '0.0.0.0');
+  logger.log(`Gateway listening on port ${port}`);
 }
 
 bootstrap().catch((err: unknown) => {
-  console.error(err);
+  const logger = new Logger('Bootstrap');
+  logger.error('Fatal startup error', err instanceof Error ? err.stack : String(err));
   process.exit(1);
 });

apps/gateway/src/tracing.ts

@@ -0,0 +1,42 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';
+
+const otlpEndpoint = process.env['OTEL_EXPORTER_OTLP_ENDPOINT'] ?? 'http://localhost:4318';
+
+const sdk = new NodeSDK({
+  resource: resourceFromAttributes({
+    [ATTR_SERVICE_NAME]: process.env['OTEL_SERVICE_NAME'] ?? 'mosaic-gateway',
+    [ATTR_SERVICE_VERSION]: '0.0.0',
+  }),
+  traceExporter: new OTLPTraceExporter({
+    url: `${otlpEndpoint}/v1/traces`,
+  }),
+  metricReader: new PeriodicExportingMetricReader({
+    exporter: new OTLPMetricExporter({
+      url: `${otlpEndpoint}/v1/metrics`,
+    }),
+    exportIntervalMillis: 15_000,
+  }),
+  instrumentations: [
+    getNodeAutoInstrumentations({
+      '@opentelemetry/instrumentation-fs': { enabled: false },
+      '@opentelemetry/instrumentation-dns': { enabled: false },
+    }),
+  ],
+});
+
+sdk.start();
+
+process.on('SIGTERM', () => {
+  sdk
+    .shutdown()
+    .then(() => process.exit(0))
+    .catch(() => process.exit(1));
+});
+
+export { sdk };

docker-compose.yml

@@ -0,0 +1,51 @@
+services:
+  postgres:
+    image: pgvector/pgvector:pg17
+    ports:
+      - '5432:5432'
+    environment:
+      POSTGRES_USER: mosaic
+      POSTGRES_PASSWORD: mosaic
+      POSTGRES_DB: mosaic
+    volumes:
+      - pg_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U mosaic']
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  valkey:
+    image: valkey/valkey:8-alpine
+    ports:
+      - '6379:6379'
+    volumes:
+      - valkey_data:/data
+    healthcheck:
+      test: ['CMD', 'valkey-cli', 'ping']
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:0.100.0
+    ports:
+      - '4317:4317' # OTLP gRPC
+      - '4318:4318' # OTLP HTTP
+    volumes:
+      - ./infra/otel-collector.yml:/etc/otelcol-contrib/config.yaml:ro
+    depends_on:
+      jaeger:
+        condition: service_started
+
+  jaeger:
+    image: jaegertracing/jaeger:2
+    ports:
+      - '16686:16686' # Jaeger UI
+      - '4319:4317' # Jaeger OTLP gRPC (internal, collector forwards here)
+    environment:
+      COLLECTOR_OTLP_ENABLED: 'true'
+
+volumes:
+  pg_data:
+  valkey_data:

infra/otel-collector.yml

@@ -0,0 +1,35 @@
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  batch:
+    timeout: 1s
+    send_batch_size: 1024
+
+exporters:
+  otlp/jaeger:
+    endpoint: jaeger:4317
+    tls:
+      insecure: true
+  debug:
+    verbosity: basic
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp/jaeger, debug]
+    metrics:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [debug]
+    logs:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [debug]

packages/types/package.json

@@ -18,5 +18,9 @@
   "devDependencies": {
     "typescript": "^5.8.0",
     "vitest": "^2.0.0"
+  },
+  "dependencies": {
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1"
   }
 }

packages/types/src/agent/index.ts

@@ -0,0 +1,4 @@
+/** Opaque handle for agent sessions — callers should not access internals */
+export interface AgentSessionHandle {
+  readonly id: string;
+}

packages/types/src/chat/chat.dto.ts

@@ -0,0 +1,17 @@
+import { IsString, IsNotEmpty, IsOptional, IsUUID, MaxLength } from 'class-validator';
+
+export class ChatMessageDto {
+  @IsOptional()
+  @IsUUID(4)
+  conversationId?: string;
+
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(32_000)
+  content!: string;
+}
+
+export class ChatResponseDto {
+  conversationId!: string;
+  text!: string;
+}

packages/types/src/chat/events.ts

@@ -0,0 +1,62 @@
+export interface MessageAckPayload {
+  conversationId: string;
+  messageId: string;
+}
+
+export interface AgentStartPayload {
+  conversationId: string;
+}
+
+export interface AgentEndPayload {
+  conversationId: string;
+}
+
+export interface AgentTextPayload {
+  conversationId: string;
+  text: string;
+}
+
+export interface AgentThinkingPayload {
+  conversationId: string;
+  text: string;
+}
+
+export interface ToolStartPayload {
+  conversationId: string;
+  toolCallId: string;
+  toolName: string;
+}
+
+export interface ToolEndPayload {
+  conversationId: string;
+  toolCallId: string;
+  toolName: string;
+  isError: boolean;
+}
+
+export interface ErrorPayload {
+  conversationId: string;
+  error: string;
+}
+
+export interface ChatMessagePayload {
+  conversationId?: string;
+  content: string;
+}
+
+/** Socket.IO typed event map: server → client */
+export interface ServerToClientEvents {
+  'message:ack': (payload: MessageAckPayload) => void;
+  'agent:start': (payload: AgentStartPayload) => void;
+  'agent:end': (payload: AgentEndPayload) => void;
+  'agent:text': (payload: AgentTextPayload) => void;
+  'agent:thinking': (payload: AgentThinkingPayload) => void;
+  'agent:tool:start': (payload: ToolStartPayload) => void;
+  'agent:tool:end': (payload: ToolEndPayload) => void;
+  error: (payload: ErrorPayload) => void;
+}
+
+/** Socket.IO typed event map: client → server */
+export interface ClientToServerEvents {
+  message: (data: ChatMessagePayload) => void;
+}

packages/types/src/chat/index.ts

@@ -0,0 +1,14 @@
+export { ChatMessageDto, ChatResponseDto } from './chat.dto.js';
+export type {
+  MessageAckPayload,
+  AgentStartPayload,
+  AgentEndPayload,
+  AgentTextPayload,
+  AgentThinkingPayload,
+  ToolStartPayload,
+  ToolEndPayload,
+  ErrorPayload,
+  ChatMessagePayload,
+  ServerToClientEvents,
+  ClientToServerEvents,
+} from './events.js';

packages/types/src/index.ts

@@ -1 +1,4 @@
 export const VERSION = '0.0.0';
+
+export * from './chat/index.js';
+export * from './agent/index.js';

packages/types/tsconfig.json

@@ -2,7 +2,9 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src"
+    "rootDir": "src",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "dist"]