boc/docs/ENGINEERING_STANDARD_v1.0.md

# Engineering Standard v1.0

> **LandveX utvecklas genom små, testade, versionshanterade förändringar. Varje förändring ska vara reproducerbar, granskbar och möjlig att återställa. Ingen kod skrivs direkt mot driftmiljöer eller lagringstjänster.**

---

## 1. Grundprincip

**Domänen äger sanningen. All annan kod är utbytbar.**

Prioritetsordning:

```
Domain
↓
Application
↓
Infrastructure
↓
API
↓
UI
```

Ingen kod får bryta den riktningen.

---

## 2. Teknisk Stack

### Frontend
- React
- TypeScript (`strict: true`)
- Vite
- TanStack Query
- React Router
- MapLibre GL eller Google Maps (beroende på behov)
- Tailwind CSS

### Backend
- Node.js LTS
- TypeScript (`strict`)
- Express eller Fastify
- Zod för validering
- PostgreSQL
- Redis (för köer/caching när det behövs)
- S3-kompatibel objektlagring (AWS S3, Cloudflare R2 eller MinIO lokalt)

### AI
- Python-mikrotjänster
- PyTorch
- Ultralytics/YOLO
- Grounding DINO
- SAM
- MLflow för modellversionering (senare)

### Infrastruktur
- Docker (lokal utveckling)
- Docker Compose (dev/pilot)
- **Kubernetes (plattformens målarkitektur)**
- GitOps (ArgoCD/Flux) — aldrig manuella ändringar i kluster

**Princip:** Local-first för utvecklarupplevelsen. Kubernetes-first för plattformen.
Varje komponent byggs för att köras i Kubernetes, även om den lokalt kan startas med Docker Compose.

---

## 3. Kodstandard

Obligatoriskt:
- TypeScript strict
- ESLint
- Prettier
- Inga `any`
- Inga `console.log` i produktionskod
- Små funktioner
- Dependency Injection
- Inga globala singletons

---

## 4. Git-flöde (E-001)

Ingen kod skrivs direkt i produktion.

Alltid:

```
Issue / Story
↓
Branch
↓
Kod
↓
Tester
↓
Commit
↓
Push
↓
Pull Request
↓
Review
↓
Merge
↓
Deploy
```

Aldrig:
- ändra filer direkt på servern
- FTP
- SSH-editing
- "quick fixes" i produktion

---

## 5. Commit-standard

Format:

```
feat(mission): add upload endpoint

fix(dataset): handle missing GPS

refactor(domain): simplify artifact lineage

test(application): add replay integration tests

docs(adr): document decision pipeline
```

Commits ska vara små och fokuserade.

---

## 6. Pull Request-regler

Varje PR ska innehålla:
- Syfte
- Vad som ändrats
- Hur det testats
- Eventuella migrations
- Risker
- Skärmbilder om UI ändrats

---

## 7. Tester

Miniminivå:
- Unit-test för domän
- Integrationstest för API
- End-to-end-test för kritiska flöden

Inga nya features mergas utan relevanta tester.

---

## 8. Definition of Done

En uppgift är klar först när:
1. Koden är versionshanterad.
2. Tester passerar.
3. Kodgranskning är gjord.
4. Dokumentation är uppdaterad vid behov.
5. Feature flag används om funktionen inte ska exponeras direkt.
6. Pilotmiljön fungerar.

---

## 9. AI-agent-regler

Alla AI-agenter (inklusive SVEN och andra) ska följa samma regler:
- Arbeta endast i Git-repository.
- Skapa aldrig kod direkt i produktion.
- Föreslå migrationer istället för manuella databasändringar.
- Skriva tester tillsammans med ny funktionalitet.
- Inte ändra domänmodellen utan ett tydligt arkitekturbeslut.

---

## 10. Deployment-flöde

### Applikation

```
Local Development
↓
Git Push
↓
Pull Request
↓
Review
↓
Merge
↓
CI
↓
Container Image
↓
GitOps Repository
↓
Kubernetes
```

### Infrastruktur

```
Git
↓
Pull Request
↓
Review
↓
Merge
↓
CI
↓
Kubernetes Manifest
↓
GitOps
↓
Cluster
```

**All infrastruktur är kod.** Alla Kubernetes-manifest, Helm Charts eller motsvarande konfiguration versionshanteras, granskas och deployas via samma Git-flöde som applikationskoden.

Ingen får hoppa över steg. Ingen SSH:ar in i kluster och ändrar resurser manuellt.

---

## 11. Plattformsprincip

**En ny tjänst får inte introducera ett nytt sätt att deploya, logga, konfigurera eller övervaka.**

Alla tjänster följer samma kontrakt:
- `/health` — Health endpoint
- `/ready` — Readiness endpoint
- `/live` — Liveness endpoint
- `/metrics` — Metrics endpoint
- Structured logging (JSON)
- OpenTelemetry tracing
- Configuration via environment variables
- Secrets via Secret Manager
- `/version` — Version endpoint

## 12. Observability

Varje request och varje pipeline-körning får ett gemensamt korrelations-ID som följer hela kedjan:

```
Field Session
↓
Mission
↓
Artifact
↓
Observation
↓
Evidence
↓
Decision
```

Om något går fel ska ni kunna följa samma ID genom loggar, events och databasen.

## 13. Intelligence Lab i Plattformen

Intelligence Lab är inte ett eget kluster. Det är en uppsättning tjänster i samma plattform:

```
LandveX Platform
├── API
├── Operations
├── quiXzoom Backend
├── Mission Engine
├── Knowledge Engine
├── Decision Engine
├── Economic Engine
├── Learning Engine
├── Intelligence Lab
└── AI Workers
```

Alla delar använder samma:
- Autentisering
- RBAC
- Observability
- Event bus
- Artifact Registry
- Datamodell

## Status

- **Version:** 1.0
- **Date:** 2026-07-02
- **Binding:** All developers and AI agents
- **Complements:** E-001, EP-1.0, Architecture Principles