# Del 5–6 – Arkitektur & repostruktur

## Systemöversikt

```text
┌──────────────┐   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

```text
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.