ADR-013: Engine Architecture v1.0 — Six Engines + Orchestrator
- Reality Engine: capture reality → observations - Knowledge Engine: understand meaning → evidence, findings - Decision Engine: make actionable → decisions, recommendations - Mission Engine: determine what to collect → missions, gaps - Economic Engine: manage budgets → credits, ROI - Learning Engine: continuously improve → better models - Platform Orchestrator: coordinates via events Key principles: - Each engine independently versioned - Engines never call each other directly - All communication via events - Dashboard shows results, not engines - Intelligence Lab tests engines, not platform Next: PR-005A — Mission Import UI for MVP-0
This commit is contained in:
Bernt
@@ -0,0 +1,336 @@
|
|||||||
|
# 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
|
||||||
@@ -0,0 +1,45 @@
|
|||||||
|
# ADR-013: Engine Architecture
|
||||||
|
|
||||||
|
## Status
|
||||||
|
Accepted
|
||||||
|
|
||||||
|
## Context
|
||||||
|
LandveX has grown from a collection of components to a platform. We need clear responsibility boundaries.
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
Organize LandveX into six autonomous engines:
|
||||||
|
|
||||||
|
1. **Reality Engine** — capture reality
|
||||||
|
2. **Knowledge Engine** — understand meaning
|
||||||
|
3. **Decision Engine** — make knowledge actionable
|
||||||
|
4. **Mission Engine** — determine what to collect next
|
||||||
|
5. **Economic Engine** — manage budgets and ROI
|
||||||
|
6. **Learning Engine** — continuously improve
|
||||||
|
|
||||||
|
**Platform Orchestrator** coordinates via events. Not AI. Not Dashboard.
|
||||||
|
|
||||||
|
## Key Principles
|
||||||
|
|
||||||
|
- Each engine independently versioned
|
||||||
|
- Engines never call each other directly
|
||||||
|
- All communication via events
|
||||||
|
- Orchestrator decides flow
|
||||||
|
- Dashboard shows results, not engines
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
### Positive
|
||||||
|
- Clear responsibility boundaries
|
||||||
|
- Independent development and scaling
|
||||||
|
- Easier testing
|
||||||
|
- Better fault isolation
|
||||||
|
|
||||||
|
### Negative
|
||||||
|
- More complex event handling
|
||||||
|
- Need orchestrator
|
||||||
|
- Potential latency between engines
|
||||||
|
|
||||||
|
## Related
|
||||||
|
- ADR-011: Four-Layer Data Architecture
|
||||||
|
- ADR-012: Economic Engine
|
||||||
|
- LANDVEX_ENGINE_ARCHITECTURE_v1.0.md
|
||||||
Reference in New Issue
Block a user