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