boc/docs/design/LANDVEX_PLATFORM_ARCHITECTURE.md

# LandveX Platform Architecture

## Five Engines

LandveX is not an image analysis platform. It is an **economic control system for control intelligence**.

Five engines work together:

```
Reality Engine
  ↓
Knowledge Engine
  ↓
Decision Engine
  ↓
Mission Engine
  ↓
Economic Engine
```

User experiences sit on top:
- **quiXzoom** — data collection (Zoomers)
- **LandveX Dashboard** — decision makers
- **Intelligence Lab** — development and validation

---

## 1. Reality Engine

**Purpose:** Capture reality from the field.

**Flow:**
```
Phone → Video/Images → Upload → Immutable Archive
```

**Key objects:**
- `ArchiveArtifact` — original file, never changed
- `FieldSession` — organizes field work
- `Mission` — single data collection task

**Value question:** What reality was captured?

---

## 2. Knowledge Engine

**Purpose:** Convert raw data to structured knowledge.

**Flow:**
```
Archive Artifact → Knowledge Extraction → Knowledge Graph
```

**Key objects:**
- `KnowledgeArtifact` — extracted knowledge (observations, segmentations, embeddings)
- `Observation` — what was seen
- `Evidence` — supporting data
- `Finding` — interpreted result

**Value question:** What does it mean in our domain?

---

## 3. Decision Engine

**Purpose:** Produce verified decisions from knowledge.

**Flow:**
```
Finding → Decision → Review → Approved Decision Case
```

**Key objects:**
- `DecisionCase` — complete decision chain
- `Review` — human validation
- `Decision` — recommended action

**Value question:** What should we do?

---

## 4. Mission Engine

**Purpose:** Generate and manage data collection missions.

**Flow:**
```
Knowledge Gap → Coverage Analysis → Mission Proposal → Budget Check → Mission Created
```

**Key objects:**
- `KnowledgeGap` — missing information
- `Hotspot` — high-value area
- `Contradiction` — conflicting information
- `Mission` — data collection task

**Value question:** Where should we collect data?

---

## 5. Economic Engine

**Purpose:** Manage budgets, credits, and ROI.

**Flow:**
```
Budget → Credit Allocation → Mission Funding → Verified Delivery → Settlement → ROI
```

**Key objects:**
- `Credit` — first-class object (Mission, Validation, Training, Priority, Emergency)
- `IntelligenceLedger` — tracks value creation
- `Settlement` — payment to Zoomers

**Value question:** What did this decision cost?

---

## Cross-Cutting Objects

### Contradiction Engine
```
Source A vs Source B → Confidence → Potential Value → Suggested Mission
```

Example:
- Municipality register: "Road is newly paved"
- Our observations: "Severe cracking"
- System: "Verify this contradiction"

### Hotspot Engine
```
Observation Density + Contradictions + Customer Requests + Risk Trend + Business Value
  ↓
Hotspot Score → Mission Generator
```

### Knowledge Gap
```
Area + Coverage + Confidence + Priority + Estimated Value + Budget
  ↓
Recommended Mission
```

---

## Intelligence Ledger

Separate from financial accounting:

| Field | Description |
|-------|-------------|
| Mission | Which mission |
| Budget | Credits allocated |
| Credits Reserved | Committed |
| Credits Consumed | Spent |
| Knowledge Produced | Observations created |
| Decision Produced | Verified decisions |
| Business Impact | Measured value |
| ROI | Return on investment |

**Questions answered:**
- How many kronor did this verified Decision Case cost?
- Which municipality gives highest knowledge return per invested krona?

---

## Architecture Principles

1. **Every component answers:** What value is created here? Who pays for it?
2. **Ontology before model** — taxonomy answers "what does it mean?"
3. **AI models trained on curated datasets**, not whole archive
4. **Knowledge gaps drive missions**, not just customer orders
5. **Contradictions are opportunities**, not errors
6. **Economic engine as important as AI models**

---

## Related Documents

- ADR-011: Four-Layer Data Architecture
- DECISION_MODEL_v1.0.md
- EPIC-001-First-Verified-Decision.md