# AAMOS System Documentation

## Executive Summary

**Arkitekturmognad:** 6/10
**AI-mognad:** 7/10
**Driftmognad:** 5/10
**Säkerhetsmognad:** 4/10
**Skalbarhet:** 6/10
**Observerbarhet:** 4/10
**Kodkvalitet:** 5/10
**Agentautonomi:** 6/10
**Helhetsförståelse:** 5/10

---

## 1. High-level Architecture

### System Overview
AAMOS (Adaptive Autonomous Multi-Agent Operating System) är en distribuerad mikrotjänstarkitektur byggd för att stödja Landvex/quiXzoom-plattformen. Systemet körs på AWS infrastruktur i regionen eu-north-1 (Stockholm).

### Komponenter

#### Core Services
- **ouroboros-identity** (Port 3207) - Rust-baserad identitetstjänst med JWT-autentisering
- **aamos-ledger** (Port 3250) - Bokföringsmotor med dubbel bokföring och SIE4-stöd
- **quixzoom-app** - React/Vite frontend hostad på S3 + CloudFront
- **mission-service** - Node.js/Express API för missionshantering

#### Infrastrukturkomponenter
- **AWS EC2** - bernt.wavult.com (server-2)
- **AWS S3** - quixzoom-app-prod (frontend-hosting)
- **AWS CloudFront** - CDN för app.quixzoom.com
- **AWS RDS/PostgreSQL** - Databas för användare, transaktioner, audit
- **AWS Lambda** - quixzoom-forgot-password (lösenordsåterställning)
- **AWS SES** - E-postutskick
- **AWS API Gateway** - REST API-gateway

#### Agent Infrastructure
- **OpenClaw** - Agent runtime och orchestration
- **Bernt** - Huvudagent (AI-assistent)

### Kommunikation
- REST API:er mellan tjänster
- PostgreSQL för persistent lagring
- S3 för statisk filhosting
- CloudFront för CDN-distribution

---

## 2. Infrastructure

### Cloud
- **Provider:** AWS
- **Region:** eu-north-1 (Stockholm)
- **Konto:** 155407238699

### Compute
- **EC2 Instance:** i-09b2204a52c2f33c9
  - Typ: t4g (ARM64/Graviton)
  - OS: Amazon Linux 2023
  - Kernel: Linux 6.18.30-61.116.amzn2023.aarch64
  - Användare: bernt (wheel, NOPASSWD systemctl/journalctl)

### Containers & Orchestration
- **Ingen Kubernetes** - Tjänster körs direkt på EC2
- **Processhantering:** systemd
- **Reverse Proxy:** nginx

### Lagring
- **S3 Buckets:**
  - quixzoom-app-prod (frontend)
  - quixzoom-assets (statiska tillgångar)
- **RDS:** PostgreSQL (host okänd, behöver verifieras)
- **Lokal disk:** /opt/amos/ (konfiguration, nycklar, data)

### Nätverk
- **DNS:** app.quixzoom.com → CloudFront → S3
- **API:** api.quixzoom.com → nginx → backend-tjänster
- **SSL:** Let's Encrypt / AWS Certificate Manager

### Autoscaling
- **Ej konfigurerat** - Manuell skalning

### Secrets
- **Hantering:** Miljövariabler + lokala filer
- **Lokalisering:** /opt/amos/data/, ~/.env-filer
- **Rotation:** Manuell

---

## 3. AI Stack

### Modeller
| Modell | Storlek | Syfte | Användning | Kontext |
|--------|---------|-------|------------|---------|
| moonshot/kimi-k2.6 | Okänd | Huvudagent (Bernt) | Konversation, kodgenerering, problemlösning | Full systemkontext |
| Claude (via API) | - | Backup/assistans | Komplexa uppgifter, längre kontext | 200K tokens |

### Embedding & Reranking
- **Ingen dedikerad embedding-modell** - Använder Claude/moonshot för semantisk förståelse
- **Vector DB:** Ej implementerat

### Vision
- **Ingen dedikerad vision-modell**
- Bildhantering via frontend (React) och backend (Node.js)

### Speech
- **Ingen speech-modell** - Text-baserad interaktion

### Kostnad
- **Claude API:** Max 20 000 kr/mån (hårt tak)
- **moonshot:** Inkluderat i OpenClaw-licens

---

## 4. Agent Architecture

### Agenter

#### Bernt (Huvudagent)
- **Syfte:** Personlig AI-assistent för Erik Svensson
- **Verktyg:** Filåtkomst, kodredigering, systemkommandon, webbsökning
- **Behörigheter:** Sudo (systemctl/journalctl), AWS SSM (root), filsystem
- **Ansvarsområde:** Systemadministration, utveckling, deployment, support
- **Kommunikation:** Telegram, Discord, andra chattkanaler
- **State:** Session-baserad, persistent via MEMORY.md och dagliga loggar
- **Minne:** 
  - Korttids: Session-kontext
  - Långtids: MEMORY.md (manuellt curerat)
  - Dagligt: memory/YYYY-MM-DD.md
- **Rollback:** Manuell via git, filbackuper

### Beslutsfattande
- **Autonomi:** Bernt fattar självständiga beslut inom definierade gränser
- **Eskalering:** Frågar Erik vid:
  - Kostnader > 0 USD
  - Destruktiva operationer
  - Extern kommunikation
  - Osäkerhet

---

## 5. Tools

### MCP (Model Context Protocol)
- **OpenClaw MCP** - Agent-runtime och verktygsintegration

### REST API:er
- ouroboros-identity (port 3207)
- aamos-ledger (port 3250)
- mission-service (port ?)
- quixzoom-capture-pipeline (port ?)

### CLI-verktyg
- aws-cli
- kubectl (ej aktivt använt)
- docker (ej aktivt använt)
- systemctl/journalctl
- nginx
- certbot

### Programmeringsspråk
- **Rust** - ouroboros-identity
- **Node.js/TypeScript** - Frontend, API:er, scripts
- **Python** - Dataanalys, scripts
- **Bash** - Systemadministration

### Databaser
- **PostgreSQL** - Huvuddatabas
- **SQLite** - Lokal lagring (om någon)

### Cloud-tjänster
- AWS EC2, S3, CloudFront, Lambda, SES, API Gateway, RDS

---

## 6. Business Systems

### quiXzoom - Affärsflöden

#### Zoomer Onboarding
1. Registrering (e-post, lösenord)
2. E-postverifiering
3. Identitetsverifiering (KYC) - Pass/ID + selfie
4. Godkännande av villkor
5. Första mission

#### Mission Flow
1. Kund skapar mission
2. Zoomer accepterar mission
3. Zoomer fotograferar och laddar upp
4. AI-granskning av bilder
5. Godkännande/Avslag
6. Betalning via Stripe Connect

#### Betalningsflöde
1. Godkänd submission
2. Stripe Connect-utbetalning
3. Zoomer får pengar direkt till bankkonto

### Flaskhalsar
- **KYC-verifiering** - Manuell granskning krävs ibland
- **Betalningar** - Beroende av Stripe Connect
- **Skalning** - Ingen autoscaling konfigurerad

---

## 7. Knowledge Model

### Kunskapskällor
1. **README-filer** - Projektbeskrivningar
2. **Markdown-dokument** - MEMORY.md, AGENTS.md, SOUL.md, USER.md
3. **Git-historik** - Kodändringar, commit-meddelanden
4. **Konfigurationsfiler** - .env, nginx.conf, systemd units
5. **Runtime-kontext** - Session-specifik information

### Embeddings & Vector DB
- **Ej implementerat** - Ingen vektordatabas
- **Sökning:** Manuell filsökning, grep, find

### Kontextbyggnad
1. Bootstrap-filer laddas vid sessionstart
2. Dagliga minnen läggs till
3. Runtime-kontext injiceras
4. Användarfråga tillförs

### Information som saknas
- **Automatisk kodindexering**
- **Semantisk kod-sökning**
- **Graf-baserad kunskapsrepresentation**

---

## 8. Context Pipeline

### Steg-för-steg
1. **Bootstrap** - AGENTS.md, SOUL.md, USER.md laddas
2. **Dagligt minne** - memory/YYYY-MM-DD.md läggs till
3. **Projektkontext** - Relevanta filer identifieras och läses
4. **Runtime-kontext** - Systeminfo, kanal, capabilities
5. **Användarinput** - Fråga/kommando tillförs
6. **Verktygsanrop** - Fil-läsning, kommandokörning
7. **Respons** - Genereras baserat på all kontext

### Begränsningar
- **Kontextfönster:** Begränsat av modellens max tokens
- **Filtrering:** Ingen intelligent ranking av information
- **Minne:** Begränsat till explicit sparade filer

---

## 9. Code Intelligence

### Kod-sökning
- **ripgrep** - Snabb text-sökning
- **find** - Fil-sökning
- **Manuell navigering** - Filstruktur, importer

### Saknas
- **Semantisk kod-sökning** (t.ex. Sourcegraph, Cody)
- **AST-baserad analys**
- **LSP-integration**
- **Dependency graph**
- **Code graph**

---

## 10. Testing

### Nuvarande tester
- **Manuell testning** - Primär metod
- **Bygg-verifiering** - npm run build, cargo build

### Saknas
- [ ] Unit-tester
- [ ] Integrationstester
- [ ] E2E-tester
- [ ] Smoke-tester
- [ ] Performance-tester
- [ ] Regressionstester
- [ ] Säkerhetstester
- [ ] Load-tester
- [ ] Chaos-tester
- [ ] Mutationstester
- [ ] Code coverage

---

## 11. Deployment

### Process
1. **Lokal utveckling** - Filredigering
2. **Bygg** - npm run build / cargo build
3. **Manuell synk** - aws s3 sync / scp
4. **Cache-invalidering** - CloudFront
5. **Service-restart** - systemctl restart

### Branching
- **Ej strikt** - Direkt redigering på main/master

### CI/CD
- **Ej konfigurerat** - Ingen automatisk pipeline

### Rollback
- **Manuell** - Återställning från backup/git

---

## 12. Security

### Secrets
- **Lagring:** Miljövariabler, lokala filer
- **Rotation:** Manuell
- **Kryptering:** Ej konfigurerat för secrets i vila

### IAM
- **AWS:** Grundläggande roller
- **Lokal:** sudo-grupper

### Audit
- **Systemloggar:** journalctl
- **Applikationsloggar:** Olika per tjänst
- **Centraliserad loggning:** Ej konfigurerat

### Saknas
- [ ] Automatisk secret-rotation
- [ ] SBOM-generering
- [ ] Supply chain scanning
- [ ] OWASP-top-10 genomgång
- [ ] Penetrationstester

---

## 13. Performance

### Nuvarande status
- **CPU:** Låg belastning (t4g är kraftfull för nuvarande load)
- **RAM:** Tillräckligt
- **GPU:** Ej använd
- **Lagring:** S3 för statiskt, RDS för data

### Flaskhalsar
- **Cold starts** - Lambda-funktioner
- **Cache** - CloudFront, men ej optimalt konfigurerat
- **Databas** - Okänd prestanda

---

## 14. Cost

### Nuvarande kostnader (uppskattade)
| Post | Kostnad/mån |
|------|-------------|
| AWS EC2 (t4g) | ~500 kr |
| AWS S3 | ~50 kr |
| CloudFront | ~100 kr |
| RDS | ~500 kr |
| Claude API | Max 20 000 kr |
| **Totalt** | **~21 000 kr/mån** |

### Största kostnadsdrivare
1. Claude API (20 000 kr/mån)
2. AWS-infrastruktur (~1 000 kr/mån)

---

## 15. Technical Debt

### Prioriterad lista

1. **Inga automatiska tester** - Risk för regressioner
2. **Ingen CI/CD** - Manuell deployment är felbenäget
3. **Ingen autoscaling** - Kan inte hantera plötslig load
4. **Bristfällig observerbarhet** - Svårt att diagnostisera problem
5. **Ingen centraliserad loggning** - Loggar spridda över systemet
6. **Manuell secret-hantering** - Säkerhetsrisk
7. **Ingen backup-strategi** - Dataförlustrisk
8. **Ingen disaster recovery** - Lång återhämtningstid
9. **Bristfällig dokumentation** - Svårt att onboarda nya
10. **Ingen kodgranskning** - Kvalitetsrisk

---

## 16. Missing Components

För att bli en världsklassplattform:

1. **Automatiserad CI/CD-pipeline**
2. **Komplett testsvit** (unit, integration, E2E)
3. **Observerbarhet-stack** (Prometheus, Grafana, Loki)
4. **Automatisk skalning** (Kubernetes eller ECS)
5. **Centraliserad loggning**
6. **Säkerhetsskanning** (SAST, DAST, dependency scanning)
7. **Backup och disaster recovery**
8. **Dokumentationsgenerering**
9. **Semantisk kod-sökning**
10. **Feature flags**

---

## 17. Self Awareness

### Begränsningar
- **Ingen realtidskontroll** av systemet
- **Begränsad kontext** - Kan inte se allt samtidigt
- **Ingen automatisk upptäckt** av nya tjänster/komponenter
- **Manuellt minne** - Måste explicit spara information

### Vad som skulle underlätta
- **Automatisk systemupptäckt** - Skanna och kartlägga kontinuerligt
- **Centraliserad kunskapsbas** - Vector DB med all systeminfo
- **Automatisk dokumentationsuppdatering**
- **Self-healing** - Automatisk feldetektion och återställning

### För att en ny agent ska kunna ta över
- **Komplett systemdokumentation** (denna fil)
- **Automatisk kontextinjektion** - All relevant info vid sessionstart
- **Graf-baserad kunskapsrepresentation** - Relationer mellan komponenter
- **Automatisk upptäckt** - Agenten ska kunna utforska systemet själv

---

## 18. Top 10 Förbättringar (Prioriterade)

1. **Implementera CI/CD** - GitHub Actions eller AWS CodePipeline
2. **Skriv tester** - Börja med unit-tester för kritiska komponenter
3. **Sätt upp observerbarhet** - Prometheus + Grafana
4. **Automatisera deployment** - Eliminera manuella steg
5. **Implementera backup** - Automatiska databas-backuper
6. **Förbättra säkerhet** - Secret management, scanning
7. **Dokumentera API:er** - OpenAPI/Swagger för alla endpoints
8. **Sätt upp autoscaling** - Kubernetes eller ECS
9. **Implementera feature flags** - Gradvis rollout
10. **Skapa runbooks** - Standardprocedurer för vanliga operationer

---

## Appendix: Filstruktur

```
/home/bernt/
├── .openclaw/workspace/          # Agent workspace
│   ├── AGENTS.md                 # Agent-konfiguration
│   ├── MEMORY.md                 # Långtidsminne
│   ├── SOUL.md                   # Personlighet
│   ├── USER.md                   # Användarinfo
│   ├── TOOLS.md                  # Verktygsanteckningar
│   └── memory/                   # Dagliga loggar
├── repos/
│   └── quixzoom.com/             # quiXzoom frontend
│       ├── src/                  # React/Vite-kod
│       ├── infra/                # Infrastruktur
│       └── package.json
├── rust/
│   └── ouroboros-identity/       # Rust identitetstjänst
│       ├── src/main.rs
│       └── Cargo.toml
├── services/                     # Node.js-tjänster
│   └── ouroboros-identity-proxy/ # Auth proxy
├── quixzoom-forgot-password-lambda/  # Lambda-funktion
└── quixzoom-app-www/             # Byggd frontend

/opt/amos/                        # Systemdata
├── data/keys/                    # JWT-nycklar
└── MEMORY.md                     # Legacy-minne
```

---

*Dokumentation genererad av Bernt (AI-agent)*
*Senast uppdaterad: 2026-06-30*