Cibello-app/docs/05-arkitektur.md

Del 5–6 – Arkitektur & repostruktur

Systemöversikt

┌──────────────┐   HTTPS/JSON    ┌─────────────────────────────┐
│  iOS/Android  │ ──────────────▶ │         Food API            │
│  (Expo RN)    │ ◀────────────── │        (Fastify)            │
└──────────────┘                  │  auth · inventory · recipes │
      │  presigned PUT            │  meals · plan · shopping    │
      ▼                           │  recs · memory · subs · adm │
┌──────────────┐                  └──────┬──────────┬───────────┘
│  S3 (bilder) │ ◀── presigned ──────────┘          │ enqueue
└──────┬───────┘                                    ▼
       │ läs-URL                          ┌──────────────────┐
       │                                  │  Redis / BullMQ  │
       ▼                                  └────────┬─────────┘
┌──────────────┐    typade kontrakt                │ konsumerar
│    AAMOS     │ ◀───────────────────────┌─────────▼─────────┐
│ (befintlig   │ ─────────────────────▶  │      Worker       │
│ AI-plattform)│    validerade svar      │ bildanalys·kvitto │
└──────────────┘                         │ plan·minne·notiser│
                                         └─────────┬─────────┘
                    ┌────────────┐                 │
                    │ PostgreSQL │ ◀───────────────┘
                    │   (app)    │ ◀── Adminpanel (Vite/React) via /admin/v1
                    └────────────┘

Regler som bär arkitekturen (spec §31, §61): mobilen pratar endast med Food API; AAMOS nås endast från API/worker via @app/ai-contracts (Zod-validerad input och output – brutet kontrakt är ett fel, aldrig data); alla säkerhetskritiska beräkningar (nutrition, allergener, saldo, entitlements) är deterministiska paket; AI-resultat blir aldrig lagerdata utan användarbekräftelse.

Centrala dataflöden

Skanning (spec §50): App → POST /v1/scans (kvot + presign) → PUT bild → POST /scans/:id/start → kö → worker → AAMOS → validerat resultat → awaiting_confirmation → app granskar → POST /scans/:id/confirm → inventory- transaktioner + events + ai_corrections (samtyckessnapshot).

"Vad ska vi äta?": API läser lager+medlemsbegränsningar+dagsläge+säsong → deterministisk säkerhetsfiltrering → täckning (recipe-engine) → poäng+förklaring (recommendation-engine) → ev. AAMOS-omrankning (flagga) → matlådor först.

Events (spec §55): skrivs i outbox-tabellen i samma transaktion som affärsdata; worker publicerar var 30:e sekund; minnesjobbet konsumerar veckans events per användare med samtycke → AAMOS UPDATE_USER_MEMORY → förslag till memory_items.

Repostruktur och ansvar per paket

apps/
  mobile/   Expo-app. Får ALDRIG innehålla AI-nycklar eller premiumlogik (§61.13–14).
  api/      Enda ingången. Routes per domän, plugins (auth/core/storage), tunna handlers.
  worker/   BullMQ-processorer för spec §54-jobben + schemalagda jobb.
  admin/    Vite/React-panel mot /admin/v1 (§57).

packages/
  shared-types/           Enums, entiteter, konstanter. Noll beroenden. Allas sanning.
  validation/             Zod-scheman för API-kontrakt (in-DTO:er).
  database/               Drizzle-schema (54 tabeller), klient, migrationer, seed.
  nutrition-engine/       §21: enheter, per-100-beräkning, BMR/TDEE, dagsmål. Rent.
  inventory-engine/       §8/§13: saldo, FEFO, bäst före-klassning, dubbletter, forecast.
  recipe-engine/          §17/§20: säkerhet (allergi/diet/religion), täckning, skalning, substitution, kostnad.
  recommendation-engine/  §18–19/§28: poängvikter, förklaringar (sv), craving-parser, säsongsalgoritmer.
  ai-contracts/           §31: AAMOS task-typer, Zod-kuvert, HttpAamosClient + MockAamosClient.
  memory-client/          §32: minnesförslag via AAMOS, "Vad appen vet"-vy, pseudonymisering.
  subscriptions/          §44–47: entitlements, signerad offline-token, StoreVerifier.
  connectors/             §43: interface + Livsmedelsverket, Open Food Facts, hälso-stubs.
  events/                 §55: typade payloads + makeEvent.
  feature-flags/          DB+env-flaggor med rollout-procent.

infrastructure/           Docker, compose (dev+prod), migrations (genererad SQL),
                          deployment (DB-bootstrap, deploy.sh), monitoring, security.
docs/                     Denna dokumentation (Del 1–20).

Beroenderiktning: apps → packages, packages → shared-types, aldrig tvärtom och aldrig paket ↔ paket-cykler. Motorerna är rena funktioner (inga DB-anrop) → triviala att testa och att flytta till egen tjänst vid skalning (§59 steg 2–3 kräver inga kodändringar i motorerna, bara i apps/).

Service-to-service (§59)

API↔AAMOS: HTTPS, Bearer-nyckel, timeout+exponentiell retry, correlation-id-header, versionerat kontrakt (x-contract-version). Circuit breaker läggs i HttpAamosClient när trafik finns att kalibrera mot. Samma API-domän behålls genom alla skalningssteg.