boc/SYSTEM_GRAPH.md

# AAMOS System Knowledge Graph

> Levande modell av systemet. Inte dokumentation — verklighet.

---

## Aktörer (Actors)

```
┌─────────┐     ┌──────────┐     ┌─────────────┐
│ Zoomer  │     │ Customer │     │ Admin/Landvex│
└────┬────┘     └────┬─────┘     └──────┬──────┘
     │               │                  │
     └───────────────┴──────────────────┘
                     │
                     ▼
              ┌─────────────┐
              │  quiXzoom   │
              │    App      │
              │ React/Vite  │
              └──────┬──────┘
                     │
                     ▼
              ┌─────────────┐
              │   nginx/    │
              │  API Gateway│
              └──────┬──────┘
                     │
         ┌───────────┼───────────┐
         │           │           │
         ▼           ▼           ▼
    ┌────────┐ ┌────────┐ ┌────────┐
    │  Auth  │ │Mission │ │ Wallet │
    │Rust/   │ │Node.js │ │Node.js │
    │axum    │ │        │ │        │
    └───┬────┘ └───┬────┘ └───┬────┘
        │          │          │
        └──────────┼──────────┘
                   │
                   ▼
            ┌─────────────┐
            │ PostgreSQL  │
            │    (RDS)    │
            └─────────────┘
```

---

## Affärsflöden (Business Flows)

### 1. Zoomer Onboarding
```
Zoomer ──► App ──► Auth.register ──► DB.users
  │
  ▼
E-postverifiering
  │
  ▼
KYC-start ──► App ──► Identity.session ──► DB.sessions
  │
  ▼
Passfoto + Selfie ──► KYC.upload ──► S3
  │
  ▼
KYC.verify ──► AI-granskning
  │
  ▼
Godkänd ──► DB.users (kyc_status=verified)
  │
  ▼
Kan ta missions
```

### 2. Mission Flow
```
Customer ──► App ──► Mission.create ──► DB.missions
                                              │
                                              ▼
Zoomer ──► App ──► Mission.list ◄─────────────┘
  │
  ▼
Claim ──► DB.claims (status=active)
  │
  ▼
Fotografera ──► App ──► Submission.create ──► S3 (bilder)
  │
  ▼
AI-granskning ──► Mission.review
  │
  ├─► Godkänd ──► DB.submissions (approved)
  │       │
  │       ▼
  │   Payout.request ──► Stripe Connect
  │       │
  │       ▼
  │   Zoomer får pengar
  │
  └─► Avslag ──► DB.submissions (rejected)
          │
          ▼
      Zoomer kan försöka igen
```

### 3. Betalningsflöde (Customer)
```
Customer ──► App ──► Wallet.deposit ──► Stripe
  │
  ▼
DB.wallets (credits += amount)
  │
  ▼
Customer kan skapa missions
```

### 4. Lösenordsåterställning (NYTT)
```
Zoomer ──► App ──► Auth.forgot-password
  │
  ▼
API Gateway ──► Lambda (quixzoom-forgot-password)
  │
  ├─► DB.password_reset_tokens (skapa token)
  │
  └─► SES (skicka e-post)
          │
          ▼
      Zoomer får mejl med länk
          │
          ▼
      Klickar länk ──► App ──► ResetPassword.tsx
          │
          ▼
      Ange nytt lösenord ──► Lambda.verify ──► Lambda.reset
          │
          ▼
      DB.users (uppdatera password_hash)
      DB.password_reset_tokens (markera used)
```

---

## Beroenden (Dependencies)

### Kritiska vägar

**Om Stripe ligger nere:**
- ❌ Payout fungerar inte → Zoomers får inte betalt
- ❌ Wallet.deposit fungerar inte → Kunder kan inte köpa credits
- ✅ Mission-granskning fungerar fortfarande
- ✅ KYC fungerar fortfarande

**Om PostgreSQL ligger nere:**
- ❌ ALLT slutar fungera
- ❌ Auth, Mission, Wallet, KYC — alla döda
- ⚠️ Ingen dokumenterad backup-strategi
- ⚠️ Ingen dokumenterad disaster recovery

**Om S3 ligger nere:**
- ❌ Bilduppladdning fungerar inte
- ❌ Frontend kan inte ladda assets
- ✅ API:er fungerar fortfarande
- ✅ Auth fungerar fortfarande

**Om CloudFront ligger nere:**
- ⚠️ App laddar långsamt (direkt från S3)
- ✅ Fungerar fortfarande

**Om SES ligger nere:**
- ❌ Lösenordsåterställning fungerar inte
- ✅ Allt annat fungerar

---

## Dataflöden (Data Flows)

### Tabell: missions
Används av:
- Mission Service (CRUD)
- App (visa på karta)
- Customer (skapa)
- Zoomer (claima)

### Tabell: users
Används av:
- Auth Service (autentisering)
- KYC Service (verifiering)
- Wallet Service (transaktioner)
- App (profil)

### Tabell: claims
Används av:
- Mission Service (aktiva claims)
- Zoomer (min status)
- App (UI-state)

### Tabell: submissions
Används av:
- Mission Service (granskning)
- AI-granskning (bilder)
- Payout Service (betalning)

---

## Teknisk skuld (Technical Debt) — Graf-baserad vy

```
Manuell deployment ──► Risk för mänskliga fel
        │
        ▼
Inga automatiska tester ──► Regressioner upptäcks sent
        │
        ▼
Ingen CI/CD ──► Lång ledtid från kod till produktion
        │
        ▼
Ingen autoscaling ──► Kan inte hantera plötslig load
        │
        ▼
Bristfällig observerbarhet ──► Svårt att diagnostisera
        │
        ▼
Ingen centraliserad loggning ──► Tidskrävande felsökning
```

---

## Agentens roll i systemet

```
Bernt (AI-agent)
  │
  ├─► Utvecklar ──► quixzoom.com (frontend)
  │
  ├─► Administrerar ──► ouroboros-identity (auth)
  │
  ├─► Deployar ──► S3 + CloudFront
  │
  ├─► Underhåller ──► PostgreSQL (RDS)
  │
  └─► Konfigurerar ──► AWS-resurser
```

**Begränsningar:**
- Ingen realtidskontroll av systemet
- Begränsad kontext — kan inte se allt samtidigt
- Ingen automatisk upptäckt av nya komponenter
- Manuellt minne — måste explicit spara information

---

## Förändringspåverkan (Change Impact)

### "Vad påverkas om jag ändrar..."

**Wallet-modulen?**
- Direkt: Wallet Service, DB.wallets, DB.transactions
- Indirekt: Payout Service, App (Wallet-sida), Zoomer (utbetalningar)
- Tester som behövs: Wallet-transaktioner, Payout-integration

**KYC-flödet?**
- Direkt: KYC Service, Identity Service, DB.sessions
- Indirekt: Auth Service, App (VerifyIdentity.tsx), Zoomer (onboarding)
- Tester som behövs: KYC-verifiering, Session-hantering

**Mission-API:et?**
- Direkt: Mission Service, DB.missions, DB.claims
- Indirekt: App (karta, lista), Zoomer (claim), Customer (skapa)
- Tester som behövs: Mission-CRUD, Claim-livscykel

---

## Saknade länkar (Missing Links)

1. **Ingen koppling mellan KYC och Wallet**
   - Zoomer kan ha verifierad KYC men ingen wallet
   - Borde: KYC godkänd → auto-skapa wallet

2. **Ingen koppling mellan Submission och Notification**
   - Zoomer får inte veta när submission granskats
   - Borde: Submission godkänd/avslagen → push-notis

3. **Ingen koppling mellan Customer och Analytics**
   - Customer ser inte mission-statistik
   - Borde: Dashboard med mission-performance

4. **Ingen koppling mellan Agent och Monitoring**
   - Bernt vet inte om systemet är nere
   - Borde: Agent får alerts, kan reagera automatiskt

---

*Denna graf är levande — uppdateras när systemet förändras.*
*Genererad av Bernt (AI-agent) *
*Senast uppdaterad: 2026-06-30*