diff --git a/docs/design/LANDVEX_ENGINE_ARCHITECTURE_v1.0.md b/docs/design/LANDVEX_ENGINE_ARCHITECTURE_v1.0.md new file mode 100644 index 000000000..532bdb26c --- /dev/null +++ b/docs/design/LANDVEX_ENGINE_ARCHITECTURE_v1.0.md @@ -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 diff --git a/docs/design/adr/ADR-013-Engine-Architecture.md b/docs/design/adr/ADR-013-Engine-Architecture.md new file mode 100644 index 000000000..d31c01a71 --- /dev/null +++ b/docs/design/adr/ADR-013-Engine-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