// ❌ Anti-Pattern — LLM treated as a deterministic REST endpoint
// file: src/controllers/AiController.ts

import express from 'express'
import OpenAI from 'openai'

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
const router = express.Router()

router.post('/chat', async (req, res) => {
  const { message, history } = req.body

  // Raw string concatenation — no schema, no validation, no budget
  const prompt = history.map((m: any) => `${m.role}: ${m.content}`).join('\n')
  
  try {
    const completion = await openai.chat.completions.create({
      model: 'gpt-4o',
      messages: [
        { role: 'system', content: 'You are a helpful assistant.' },
        ...history,
        { role: 'user', content: message },
      ],
    })

    // Treating model output as trusted data — zero validation
    const aiResponse = completion.choices[0].message.content

    // Directly passing model output to a downstream mutation
    await db.messages.create({ role: 'assistant', content: aiResponse })

    res.json({ reply: aiResponse })
  } catch (error) {
    res.status(500).json({ error: 'AI failed' }) // Opaque, unrecoverable
  }
})

// ✅ Correct Pattern — Gateway with trust boundary
// file: src/gateway/AiGateway.ts

import { z } from 'zod'
import { StreamingGateway } from './StreamingGateway'
import { ContextScheduler } from './ContextScheduler'
import { RateLimiter } from './RateLimiter'

// Every AI response shape is declared as a Zod schema at the boundary
const WorkspaceActionSchema = z.object({
  type: z.enum(['canvas_node', 'text_reply', 'tool_call']),
  payload: z.unknown(),
  confidence: z.number().min(0).max(1),
}).strict()

type WorkspaceAction = z.infer<typeof WorkspaceActionSchema>

export class AiGateway {
  constructor(
    private readonly streaming: StreamingGateway,
    private readonly scheduler: ContextScheduler,
    private readonly limiter: RateLimiter,
  ) {}

  async *streamResponse(
    request: GatewayRequest,
    signal: AbortSignal,
  ): AsyncGenerator<WorkspaceAction> {
    // Invariant 1: Rate compliance before touching the provider
    await this.limiter.acquire(request.orgId, request.estimatedTokens)

    // Invariant 2: Context scheduled before sending to model
    const scheduledMessages = this.scheduler.pack(request.messages, request.ragChunks)

    // Stream from provider — tokens stay raw until validated
    for await (const rawChunk of this.streaming.stream(scheduledMessages, signal)) {
      // Invariant 3: Structural validity at the boundary
      const parsed = WorkspaceActionSchema.safeParse(rawChunk)
      if (!parsed.success) {
        // Invariant violation: log, repair, or skip — never crash
        continue
      }
      yield parsed.data // Only validated, typed data exits the gateway
    }
  }
}

# docker-compose.yml — local infrastructure stack

services:
  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_DB: workspace_dev
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev_secret
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis/redis-stack:7.4.0-v0
    ports:
      - "6379:6379"  # Redis
      - "8001:8001"  # RedisInsight UI

  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    # Run after start: docker exec ollama ollama pull llama3.2:3b
    # Run after start: docker exec ollama ollama pull nomic-embed-text

volumes:
  postgres_data:
  ollama_data:

// ✅ Correct Pattern — Provider-agnostic model client factory
// file: src/providers/ModelClientFactory.ts

import { createOpenAI } from '@ai-sdk/openai'
import { createAnthropic } from '@ai-sdk/anthropic'

export type ModelProvider = 'anthropic' | 'openai' | 'ollama'

export function createModelClient(provider: ModelProvider) {
  switch (provider) {
    case 'anthropic':
      return createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY! })
    case 'openai':
      return createOpenAI({ apiKey: process.env.OPENAI_API_KEY! })
    case 'ollama':
      // Local Ollama — zero cost, deterministic for tests
      return createOpenAI({
        baseURL: 'http://localhost:11434/v1',
        apiKey: 'ollama', // required by SDK but unused
      })
  }
}

// Environment-driven selection: tests always use 'ollama'
export const defaultProvider: ModelProvider =
  (process.env.AI_PROVIDER as ModelProvider) ?? 'ollama'

enterprise-ai-workspace/
├── apps/
│   ├── web/                      ← React 19 frontend (Vite)
│   │   ├── src/
│   │   │   ├── features/
│   │   │   │   ├── chat/         ← Streaming chat UI (Parts 6, 7)
│   │   │   │   ├── canvas/       ← Collaborative canvas (Part 7, 18)
│   │   │   │   └── approvals/    ← Human-in-the-loop UI (Part 17)
│   │   │   └── workers/
│   │   │       └── pii.worker.ts ← WebGPU PII filter (Part 21)
│   └── gateway/                  ← Fastify Node.js AI Gateway
│       ├── src/
│       │   ├── gateway/          ← Trust boundary (Parts 1–5)
│       │   ├── retrieval/        ← RAG pipeline (Parts 8–14)
│       │   ├── agents/           ← FSM + MCP workers (Parts 15–18)
│       │   └── cache/            ← Semantic caching (Part 19)
├── packages/
│   ├── db/                       ← Drizzle schema (PostgreSQL + pgvector)
│   ├── ai-schemas/               ← Shared Zod schemas (Part 3)
│   └── mcp-tools/                ← Custom MCP server (Part 16)
└── docker-compose.yml