# LandveX Engine Architecture v1.0

## Platform Overview

LandveX is not a collection of services. It is a **platform of autonomous engines** with clear responsibilities.

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

**Platform Orchestrator** coordinates engines via events. Not AI. Not Dashboard. Just orchestration.

---

## Engine 1 — Reality Engine

**Responsibility:** Transform reality into verified observations.

**Input:**
- quiXzoom (phone)
- Drones
- Cameras
- Video
- GIS
- Sensors

**Output:**
- `Observation`
- `Artifact`
- `Metadata`

**Domain objects created:**
- `FieldSession`
- `Mission`
- `Observation`
- `ArchiveArtifact`

**Events produced:**
- `ObservationCreated`
- `MissionCompleted`
- `ArtifactRegistered`

**KPIs:**
- Observations per hour
- Upload success rate
- Metadata completeness

---

## Engine 2 — Knowledge Engine

**Responsibility:** Understand what observations mean.

**Input:**
- `Observation`
- `ArchiveArtifact`

**Output:**
- `Evidence`
- `Finding`
- `KnowledgeArtifact`
- Ontology entries
- Taxonomy classifications
- Object relations
- Knowledge Graph updates

**Domain objects created:**
- `Evidence`
- `Finding`
- `KnowledgeArtifact`

**Events consumed:**
- `ObservationCreated`

**Events produced:**
- `EvidenceCreated`
- `FindingCreated`
- `KnowledgeExtracted`

**KPIs:**
- Knowledge extraction accuracy
- Ontology coverage
- Taxonomy completeness

---

## Engine 3 — Decision Engine

**Responsibility:** Make knowledge actionable.

**Input:**
- `Finding`
- `Evidence`
- Knowledge Graph

**Output:**
- `Decision`
- `Priority`
- `Confidence`
- `Consequence`
- `Recommendation`

**Domain objects created:**
- `DecisionCase`
- `Decision`
- `Review`

**Events consumed:**
- `FindingCreated`

**Events produced:**
- `DecisionCreated`
- `DecisionApproved`
- `DecisionRejected`

**KPIs:**
- Decision accuracy
- Time to decision
- Review completion rate

---

## Engine 4 — Mission Engine

**Responsibility:** Determine what data to collect next.

**Input:**
- `KnowledgeGap`
- `Hotspot`
- `Contradiction`
- Customer requests
- Budget
- SLA

**Output:**
- `Mission`
- `Reward`
- `Priority`
- `Coverage`

**Domain objects created:**
- `Mission`
- `KnowledgeGap`
- `Hotspot`
- `Contradiction`

**Events consumed:**
- `KnowledgeGapIdentified`
- `ContradictionDetected`

**Events produced:**
- `MissionCreated`
- `MissionAssigned`
- `MissionCompleted`

**KPIs:**
- Knowledge gap closure rate
- Mission success rate
- Coverage improvement

---

## Engine 5 — Economic Engine

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

**Input:**
- `Budget`
- `Mission`
- `VerifiedDelivery`

**Output:**
- `Credit`
- `Settlement`
- `ROI`
- `RewardPricing`
- `CostAllocation`

**Domain objects created:**
- `Credit`
- `CreditBudget`
- `IntelligenceLedgerEntry`

**Events consumed:**
- `MissionCompleted`
- `DecisionApproved`

**Events produced:**
- `CreditsAllocated`
- `PaymentSettled`
- `RoiCalculated`

**KPIs:**
- Cost per decision
- Knowledge return per credit
- Budget utilization

---

## Engine 6 — Learning Engine

**Responsibility:** Continuously improve all engines.

**Input:**
- `Outcome`
- `Decision`
- `Reality` (ground truth)

**Output:**
- Better models
- Better rules
- Better missions
- Better pricing

**Events consumed:**
- `DecisionApproved`
- `MissionCompleted`
- `OutcomeVerified`

**Events produced:**
- `ModelUpdated`
- `RulesRefined`
- `PricingAdjusted`

**KPIs:**
- Model improvement rate
- Prediction accuracy gain
- Cost reduction

---

## Platform Orchestrator

**Responsibility:** Coordinate engines via events.

**Not AI. Not Dashboard. Just orchestration.**

**Example flow:**
```
ObservationCreated
  ↓
Knowledge Engine (extract knowledge)
  ↓
Decision Engine (create decision)
  ↓
Mission Engine (check for gaps)
  ↓
Economic Engine (calculate ROI)
```

**Rules:**
- Engines never call each other directly
- All communication via events
- Orchestrator decides which engine runs next
- Each engine is independently versioned

---

## Dashboard

**Dashboard never shows engines.**

**Dashboard shows results:**
```
AREA
  Score
  ↓
  Top Decisions
  ↓
  Hotspots
  ↓
  Business Impact
  ↓
  Recommended Actions
```

---

## Intelligence Lab

**Intelligence Lab is the development environment for engines.**

**Test:**
- Knowledge Engine
- Decision Engine
- Learning Engine

**Not:**
- Whole platform
- Production data
- End-to-end flows

---

## Engine Contracts

Each engine MUST define:

| Contract | Description |
|----------|-------------|
| **Responsibility** | What this engine does |
| **Input** | What it consumes |
| **Output** | What it produces |
| **Domain Objects** | What it can create/modify |
| **Events In** | Events it listens to |
| **Events Out** | Events it produces |
| **KPIs** | How quality is measured |

---

## Development Principles

1. **Each engine independently versioned**
2. **Engines never call each other directly**
3. **All communication via events**
4. **Orchestrator decides flow**
5. **Dashboard shows results, not engines**
6. **Intelligence Lab tests engines, not platform**

---

## Related Documents

- ADR-011: Four-Layer Data Architecture
- ADR-012: Economic Engine
- LANDVEX_PLATFORM_ARCHITECTURE.md