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