Ur repot

Arkitekturen — hur Stacken hänger ihop, och varför

Vad detta är: ingången för någon som vill förstå plattformen utan att läsa 117 beslutsposter först. Dokumentet är en förklaring — inte en sanningskälla. Sanningskällorna är tre, och de vinner alltid över den här filen:

Koden är sanningen. Hittar du en motsägelse mellan den här filen och koden är filen fel.

Sist verifierad mot koden: 2026-08-28 (11 tjänster, 4 frontends, 6 libs, 17 vakter).

1. Vad plattformen är

Stacken är ett metadata-kontrollplan för AI-anrop. Den äger inte modellerna, inte verktygen och inte agenterna. Den äger dörrarna till dem: vem som får fråga, vilken modell frågan får gå till, vilka verktyg som får svara, vad som får loggas, hur länge det sparas och vad som kan bevisas efteråt.

Konsekvensen av att äga dörrarna och inget annat är att innehåll flödar genom plattformen i stället för att bo i den. Metadata (vem, när, vilken modell, vilket beslut, vad det kostade) skrivs i kontrollplanets Postgres. Innehåll (chattar, dokument, kunskapsbaser) ligger i tenantens eget dataplan, och det som ändå passerar kontrollplanet hashas eller maskeras.

Det är också svaret på varför tjänsterna är många och små i stället för en monolit: varje dörr är sin egen tjänst med sitt eget kontrakt, sin egen databasyta och sin egen CI-grind. Ett fel i en dörr stänger den dörren, inte plattformen.

2. Var kraven kommer ifrån

Ingen del av arkitekturen finns “för att det är god praxis”. Fyra kravkällor driver den:

1. En upphandling från en större upphandlingsorganisation — 58 SKA-krav och 2 BÖR, mappade rad för rad i repots interna forskningsunderlag. Härifrån kommer EU/EES-residens, SSO/SAML, WORM-audit, policystyrd modellrouting per informationsklass och kravet att kunna exportera allt en organisation äger.
2. Den avidentifierade kravkatalogen (Kund A–H) — policylagrets gap-analys (intern spec, §2). Åtta organisationers faktiska behov och faktiska svagheter, generaliserade till riktlinjer R1–R9. Kundnamnen finns inte i repot; kraven gör det, eftersom kraven är produktdrivande och attributionen inte är det (regeln står i AGENTS.md).
3. Kravbilden och kön — docs/10-kravbilden.md och docs/11-kon.md i digitalist-se/stacken-riktningen. Där härleds krav ur användningsfall i stället för ur koden, och där ligger arbetsordningen. Ett paket utan krav är ett paket vi inte vet varför vi bygger.
4. EU:s Cloud and AI Development Act (CADA) — kunskapsunderlaget och plattformens position ligger i repots interna analyser.

Hur ett krav blir kod

krav  →  spec i docs/superpowers/specs/  →  arbetspaket med körbart verifieringskriterium
      →  PR (per-tjänst-CI + e2e + vakter)  →  D-post i decisions.md  →  atlas-stämpel
      →  påståenderaden byter status i riktningsrepot

Kedjan är avsiktligt utan genvägar: en spec utan verifieringskriterium går inte att stänga, och ett bygge utan D-post lämnar ingen förklaring efter sig. 63 specar och 77 implementationsplaner ligger kvar som spår av exakt den rundan.

3. Kontraktet: sex skyldigheter

Det här är hela styrmodellen. Uppfyller en tjänst de sex punkterna är den en del av plattformen — allt annat är dess eget val (språk, ramverk, hosting). Fullständig text i docs/03-arkitektur.md §3 i riktningsrepot.

Skyldighet 6 är riktning, inte grind än (D-123, D-124): förmågan är beslutad men obyggd. Ett INTERNT verktyg får hålla sina egna nycklar bakom ett brokerinterface tills dess — kundens användares nycklar aldrig. Villkorstexten står i docs/03-arkitektur.md §3 i riktningsrepot, och skyldigheten skärps av sig själv när brokern finns.

Skyldighet 3 är den enda som är mekaniskt omöjlig att bryta: tools/checks/check_no_mcp_outside_gateway.py fäller varje MCP-transport som reses utanför services/mcp-gateway/app/mcp/ (D-70).

4. Lagermodellen

┌──────────────────────────────────────────────────────────────────┐
│ 4  AGENTER          (ej byggt)                                   │
├──────────────────────────────────────────────────────────────────┤
│ 3  FÖRMÅGOR         MCP-servrar — tenantens verktyg, kunskap,     │
│                     företagsminne (Shared, via delegerad identitet)│
├──────────────────────────────────────────────────────────────────┤
│ 2  AGENTMOTOR       loop · kanaler · sessionsminne ·              │
│    (ej byggt)       godkännanden · skills · subagenter            │
├──────────────────────────────────────────────────────────────────┤
│ 1  STACKEN          bff · llm-gateway · mcp-gateway · auth-api    │
│    DÖRRARNA         policy-engine · pii-api · rag-api · eval-api  │
│                     feedback-api · lifecycle-api · provisioning-api│
├──────────────────────────────────────────────────────────────────┤
│ 0  PLATTFORMEN      k3s · Postgres · secrets · GitOps · egress    │
│                     (Hetzner, customer-prod)                      │
└──────────────────────────────────────────────────────────────────┘

Lager 1 är byggt: ~42 800 rader produktionskod i services/, ~2 100 i libs/, och ~93 300 rader test. Testmassan är dubbelt så stor som koden, och det är avsiktligt — grundkravet är förvaltningsbarhet, inte kodvolym.

Lager 2 och 4 är obyggda. Att de ändå står i modellen är hela poängen med D-72 (“plattformen äger dörrarna, inte agentmotorn”): plattformen ska inte behöva ändras när en agentmotor tillkommer, bytas eller kastas.

5. Datapath: vad som händer med en fråga

Det här är arkitekturens kärna. Ordningen är verifierad i services/llm-gateway/gateway/api/chat.py.

Chattvägen

chat-ui ──► bff ──► llm-gateway ──► provider (residensen styrd av policy)
              │          │
              │          ├──► pii-api        (detektera + maskera in)
              │          ├──► policy-engine  (POST /v1/decide — fail-closed)
              │          ├──► audit-kedjan   (model_calls.v1 — FÖRE providern)
              │          ├──► policy-engine  (output_check — får svaret visas?)
              │          └──► usage_events   (tokens, kostnad, klass, grupp)
              └──► conversations/messages i bff:s egen krypterade store

Stegen i llm-gatewayen, i exekveringsordning:

Steg 5 före steg 6 är inte en detalj. Det är skillnaden mellan en logg och ett bevis: ett anrop kan inte ha nått en modell utan att raden finns, eftersom raden skrivs först och ett misslyckande stoppar anropet (D-116).

Verktygsvägen

agent/klient ──► mcp-gateway ──► registrerad MCP-server (http · sse · stdio)
                     │
                     ├──► grants      (vem får vilket verktyg)
                     ├──► policy-engine (decide per verktygsanrop)
                     ├──► audit-kedjan  (före anropet)
                     └──► tool_call_log (args och resultat hashade, aldrig sparade)

Fem tjänster anropar POST /v1/decide: bff, llm-gateway, mcp-gateway, rag-api, eval-api. Sex tjänster skriver till auditkedjan: auth-api, bff, llm-gateway, mcp-gateway, policy-engine, provisioning-api. Att listorna är korta och kända är poängen — en ny datapath som inte finns i dem är en regression, inte en funktion.

Auditkedjan

libs/audit_chain skriver SHA-256-kedjade rader i samma transaktion som händelsen, med FOR UPDATE-lås på kedjans huvud och en fältvitlista per kedja (policy_decisions.v1, model_calls.v1, …). Kedjan bär metadata och hashar — aldrig innehåll. tools/audit-chain validerar kedjan som CLI, och kör som dygnsjobb ur charts/policy-engine.

6. Tjänstekartan

Verifierat mot koden 2026-08-28. Detaljerna per tjänst — inklusive auth-modell och anropare — står i atlas.md; varje enskild endpoint i api-ytan.md.

Raderna är produktionskod i tjänstens paket, exklusive test och migrationer. Signalen för en ny tjänst är ~500 rader + en tabell; ingen tjänst uppfyller den (1×–19×). Det är inte ett automatiskt fel, men de fyra över 10× — llm-gateway, bff, auth-api, mcp-gateway — bär ordningen i minimalitetsregeln (D-120) som bindande: ta bort > använd det som finns > adoptera > skriv nytt, med valet utskrivet i PR:en.

Delade libs (libs/, PEP 420-namespace, aldrig PyPI): audit_chain (hash-kedja), platform_auth (JWT-verifiering, sub/act, scopes), policy_client (decide-anrop med timeout-golv), model_registry, observability (JSON-logg + OTel-mall), tenant_export.

Frontends (frontends/, Vite + React, npm workspaces): ops-ui (intern styryta, ~15 600 rader), chat-ui (tenantens chatt, ~5 900), platform-ui (delat designsystem, ~1 100), marketing-site.

Verktyg (tools/): audit-chain (kedjevalidator), auth-cli (break-glass), checks (17 vakter).

7. Tio val som förklarar arkitekturen

Varje rad är en beslutspost i decisions.md. Läser du bara tio, läs dessa.

8. Vad som håller ihop det mekaniskt

Arkitekturen är inte upprätthållen av disciplin. Den är upprätthållen av grindar, och det är den egenskapen som är svårast att kopiera:

• 17 vakter i tools/checks/, via pre-commit. Ett urval: check_no_mcp_outside_gateway (en MCP-väg), check_no_model_sdk_outside_gateway (provider-SDK:er bara i llm-gateway), check_no_db_outside_services (ingen egen dataväg i verktygslagret), check_atlas_freshness (kartan följer koden), check_control_surface_parity (styrytematrisen speglar koden), check_policy_timeout_floor (ingen anropare svälter policy-grinden), check_irreversible (oåterkalleligt kräver besvarat vägval), check_openapi_drift (incheckat schema == exponerat schema), check_docs_hygiene (inga kundnamn, inga maskinlokala sökvägar), check_trivyignore_expiry (varje säkerhetsdispens har motivering och slutdatum).
• 31 CI-workflows, path-filtrerade — en per tjänst och en per lib (opa test → ruff → mypy --strict → unit → integration mot riktig Postgres), resten tvärsnitt: e2e, last, helm-lint, chart-version, säkerhetsskanning, atlas-färskhet, oåterkallelighetsgrinden.
• En e2e-svit (tests/e2e/, compose-orkestrerad med Keycloak, pgvector och ärlig provider-stub) som PR-grind och post-merge-signal på main — ingen per-tjänst-svit kan se ett fel som bara uppstår när två tjänsters migrationskedjor möter varandra i en delad databas.
• Lastgrind och kapacitetsmodell — load-gate.yml + capacity-model.md: korrekthetsbärande state ligger i delad store (rate limits i Valkey, budgetar och sessioner i Postgres), aldrig enbart i pod-minne, så en per-pod-optimering får degradera skyddet men aldrig bryta korrektheten. Undantaget är dokumenterat: llm-gatewayens egen per-pod token-bucket, flaggad i kapacitetsmodellen.
• GitOps — ingen deployar imperativt. Du bumpar appVersion i tjänstens charts/<svc>/Chart.yaml och ArgoCD rullar ut; chart-version.yml fäller en glömd bump. Se deploy-gitops.md.

9. Vad som inte är byggt, och vad som inte är sant än

Ett arkitekturdokument som bara beskriver det som fungerar är säljmaterial. Läget 2026-08-28, verifierat mot koden:

Fullständig lista med status per påstående: docs/12-pastaenden.md i riktningsrepot. Regeln där är värd att låna: ett delvis som skrivs utan sitt förbehåll är ett fel, inte en förenkling.

10. Läsordning

Vill du förstå arkitekturen (2–3 timmar):

1. Den här filen.
2. docs/03-arkitektur.md i digitalist-se/stacken-riktningen — målbilden och de fem skyldigheterna i sin fulla form.
3. atlas.md — slå upp de tjänster du bryr dig om, hoppa resten. Filen är en karta, inte en berättelse.
4. De tio besluten i avsnitt 7 ovan, i decisions.md.
5. control-surfaces.md — paritetsmatrisen. Läs täckningsgränsen först; den säger vad matrisen inte granskar.

Ska du bygga något: ONBOARDING.md för miljö och kommandon, AGENTS.md för arbetsreglerna, och kön i digitalist-se/stacken-riktningen (docs/11-kon.md) för vad som ska byggas härnäst.

Ska du bedöma säkerhetsläget: SECURITY.md, incidentrunbooken i repot, och docs/02-sakerhet.md i riktningsrepot.