Initial commit (unpacked platform)

2026-08-05 19:21:11 +07:00
commit ac5340195a
314 changed files with 57584 additions and 0 deletions
@@ -0,0 +1,90 @@
+# 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.