Solution Architecture

from dataclasses import dataclass

@dataclass
class Decision:
    id: str
    title: str
    context: str        # why this decision is needed
    options: list[dict] # {name, pros, cons, cost, latency, security}
    chosen: str
    rationale: str      # why this option, given constraints

decisions = [
    Decision(
        id="ADR-001",
        title="Vector database choice",
        context="Need vector search over 50k documents with metadata filtering for RBAC.",
        options=[
            {"name": "Pinecone (managed)", "pros": "no ops", "cons": "vendor lock-in, $$", "cost": "$$$", "latency": "low", "security": "data leaves env"},
            {"name": "pgvector (Postgres)", "pros": "RBAC in SQL, no new infra, relational + vector in one", "cons": "self-managed", "cost": "$", "latency": "low", "security": "data stays in env"},
            {"name": "Qdrant (self-hosted)", "pros": "fast, no vendor lock-in", "cons": "new infra to operate", "cost": "$$", "latency": "low", "security": "data stays in env"},
        ],
        chosen="pgvector",
        rationale="Customer constraint: on-prem preferred, RBAC mandatory, existing Postgres. pgvector keeps vectors next to metadata, enabling RBAC filter at SQL level. Lowest cost, no new infra, data stays in env.",
    ),
    Decision(
        id="ADR-002",
        title="Model provider",
        context="Need BAA-covered endpoint for PHI / sensitive data.",
        options=[
            {"name": "Public OpenAI API", "pros": "easy", "cons": "no BAA, data leaves env", "cost": "$", "latency": "low", "security": "fails compliance"},
            {"name": "OpenAI Azure (enterprise)", "pros": "BAA available, regional", "cons": "enterprise pricing", "cost": "$$", "latency": "low", "security": "compliant"},
            {"name": "On-prem Llama", "pros": "data never leaves", "cons": "ops burden, lower quality", "cost": "$$", "latency": "higher", "security": "most compliant"},
        ],
        chosen="OpenAI Azure (enterprise)",
        rationale="BAA required for compliance. On-prem Llama quality gap too large for the use case. Azure enterprise offers BAA + regional residency + acceptable quality.",
    ),
]

def architecture_doc(decisions: list[Decision]) -> str:
    return "\n\n".join(
        f"## {d.id}: {d.title}\nContext: {d.context}\nChosen: {d.chosen}\nRationale: {d.rationale}"
        for d in decisions
    )