docs/architecture.md

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        USER'S BROWSER                           │
│                                                                 │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────┐ │
│  │  app/page.tsx   │───▶│ app/report/     │    │  window.    │ │
│  │                 │    │ page.tsx        │───▶│  print()    │ │
│  │  Step 1:        │    │                 │    │  (PDF)      │ │
│  │  MetricsForm    │    │  ReportView     │    └─────────────┘ │
│  │  Step 2:        │    │  BenchmarkTable │                    │
│  │  ContextForm    │    │                 │                    │
│  └────────┬────────┘    └────────▲────────┘                    │
│           │ POST                 │ sessionStorage               │
│           │ /api/interpret       │ "devops-report"              │
└───────────┼──────────────────────┼──────────────────────────────┘
            │                      │
┌───────────┼──────────────────────┼──────────────────────────────┐
│           ▼        NEXT.JS SERVER (HF Space / local)            │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              app/api/interpret/route.ts                 │    │
│  │                                                         │    │
│  │  1. Validate input (MetricsInputSchema, TeamContext)    │    │
│  │  2. loadBenchmarks()  ◀── data/benchmarks.json         │    │
│  │  3. buildSystemPrompt(benchmarks)                       │    │
│  │  4. formatMetricsMessage(metrics, context)              │    │
│  │  5. chat(system, user)  ──▶  lib/llm.ts                │    │
│  │  6. Validate response (InterpretationReportSchema)      │    │
│  │  7. Return JSON report ──────────────────────────────────────┘
│  └──────────────────────────┬──────────────────────────────┘
│                             │
│              ┌──────────────▼──────────────┐
│              │         lib/llm.ts          │
│              │  OpenAI-compatible client   │
│              │  baseURL from OLLAMA_BASE_URL│
│              └──────────────┬──────────────┘
└─────────────────────────────┼────────────────────────────────────
                              │
          ┌───────────────────┴───────────────────┐
          │                                       │
          ▼  (local dev)                          ▼  (HF Space)
  ┌───────────────┐                    ┌──────────────────────┐
  │    Ollama     │                    │  HF Inference Router │
  │  localhost:   │                    │  router.huggingface  │
  │  11434/v1     │                    │  .co/v1              │
  │               │                    │                      │
  │ llama3.1:8b   │                    │ Qwen2.5-72B-Instruct │
  └───────────────┘                    └──────────────────────┘

──────────────────── ONE-TIME SETUP ─────────────────────────────

  data/pdfs/*.pdf
       │
       ▼
  scripts/extract-knowledge.ts
  (pdf-parse → chunk → LLM → merge)
       │
       ▼
  data/benchmarks.json  ──▶  bundled into Docker image
  (47 patterns, 124 insights)