ADR-012: Five Engines Platform Architecture + Economic Engine

- LANDVEX_PLATFORM_ARCHITECTURE.md: Five Engines (Reality, Knowledge,
  Decision, Mission, Economic)
- Credit: first-class economic object with types (mission, validation,
  training, priority, emergency)
- IntelligenceLedger: tracks value creation separate from financial accounting
- KnowledgeGap: missing information that drives missions
- Hotspot: composite score for mission generation
- Contradiction: conflicting information as opportunity

Key principle: Every component answers 'What value is created here?
Who pays for it?'

Next: PR-005A — Minimal Mission Import UI for MVP-0
This commit is contained in:
Bernt
2026-07-02 16:05:56 +00:00
parent 754c89506b
commit c6e14c5928
6 changed files with 410 additions and 0 deletions
@@ -0,0 +1,184 @@
# 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
@@ -0,0 +1,41 @@
# ADR-012: Economic Engine
## Status
Accepted
## Context
LandveX is not just an image analysis platform. It is an economic control system for control intelligence. Every component must answer: What value is created here? Who pays for it?
## Decision
Model Credits as first-class objects with types:
- **Mission Credits** — fund data collection
- **Validation Credits** — pay for human review
- **Training Credits** — fund AI model training
- **Priority Credits** — expedite processing
- **Emergency Credits** — handle urgent cases
## 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 |
## Key Questions
- How many kronor did this verified Decision Case cost?
- Which municipality gives highest knowledge return per invested krona?
## Related
- ADR-011: Four-Layer Data Architecture
- LANDVEX_PLATFORM_ARCHITECTURE.md