From c6e14c59288ed33905ca596567f28b90a9f81f9a Mon Sep 17 00:00:00 2001 From: Bernt Date: Thu, 2 Jul 2026 16:05:56 +0000 Subject: [PATCH] ADR-012: Five Engines Platform Architecture + Economic Engine MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- docs/design/LANDVEX_PLATFORM_ARCHITECTURE.md | 184 ++++++++++++++++++ docs/design/adr/ADR-012-Economic-Engine.md | 41 ++++ packages/domain/src/economic/credit.ts | 57 ++++++ .../src/economic/intelligence-ledger.ts | 53 +++++ packages/domain/src/index.ts | 21 ++ packages/domain/src/mission/knowledge-gap.ts | 54 +++++ 6 files changed, 410 insertions(+) create mode 100644 docs/design/LANDVEX_PLATFORM_ARCHITECTURE.md create mode 100644 docs/design/adr/ADR-012-Economic-Engine.md create mode 100644 packages/domain/src/economic/credit.ts create mode 100644 packages/domain/src/economic/intelligence-ledger.ts create mode 100644 packages/domain/src/mission/knowledge-gap.ts diff --git a/docs/design/LANDVEX_PLATFORM_ARCHITECTURE.md b/docs/design/LANDVEX_PLATFORM_ARCHITECTURE.md new file mode 100644 index 000000000..f1e4034b9 --- /dev/null +++ b/docs/design/LANDVEX_PLATFORM_ARCHITECTURE.md @@ -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 diff --git a/docs/design/adr/ADR-012-Economic-Engine.md b/docs/design/adr/ADR-012-Economic-Engine.md new file mode 100644 index 000000000..cccb53e70 --- /dev/null +++ b/docs/design/adr/ADR-012-Economic-Engine.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 diff --git a/packages/domain/src/economic/credit.ts b/packages/domain/src/economic/credit.ts new file mode 100644 index 000000000..2d0aa1714 --- /dev/null +++ b/packages/domain/src/economic/credit.ts @@ -0,0 +1,57 @@ +/** + * Credit — First-class economic object + * + * ADR-012: Economic Engine + * Credits are not just balances. They are typed, budgeted, tracked. + */ + +export type CreditType = 'mission' | 'validation' | 'training' | 'priority' | 'emergency'; + +export interface Credit { + readonly id: string; + readonly type: CreditType; + readonly amount: number; // In smallest unit (öre/cents) + readonly currency: 'SEK' | 'EUR' | 'USD'; + readonly budgetId: string; + readonly missionId?: string; + readonly status: 'reserved' | 'consumed' | 'released'; + readonly createdAt: Date; + readonly expiresAt?: Date; +} + +export interface CreditBudget { + readonly id: string; + readonly name: string; + readonly totalAmount: number; + readonly consumedAmount: number; + readonly reservedAmount: number; + readonly creditTypes: CreditType[]; + readonly validFrom: Date; + readonly validTo: Date; +} + +export class CreditFactory { + static create(params: { + id: string; + type: CreditType; + amount: number; + currency: 'SEK' | 'EUR' | 'USD'; + budgetId: string; + missionId?: string; + expiresAt?: Date; + }): Credit { + return { + ...params, + status: 'reserved', + createdAt: new Date(), + }; + } + + static consume(credit: Credit): Credit { + return { ...credit, status: 'consumed' }; + } + + static release(credit: Credit): Credit { + return { ...credit, status: 'released' }; + } +} diff --git a/packages/domain/src/economic/intelligence-ledger.ts b/packages/domain/src/economic/intelligence-ledger.ts new file mode 100644 index 000000000..cd74e9178 --- /dev/null +++ b/packages/domain/src/economic/intelligence-ledger.ts @@ -0,0 +1,53 @@ +/** + * Intelligence Ledger — Track value creation + * + * ADR-012: Economic Engine + * Separate from financial accounting. + * Tracks: knowledge produced, decisions made, business impact, ROI. + */ + +export interface IntelligenceLedgerEntry { + readonly id: string; + readonly missionId: string; + readonly budgetId: string; + readonly creditsAllocated: number; + readonly creditsConsumed: number; + readonly observationsProduced: number; + readonly decisionsProduced: number; + readonly businessImpact?: string; + readonly roi?: number; // Percentage + readonly createdAt: Date; +} + +export interface IntelligenceLedger { + readonly entries: IntelligenceLedgerEntry[]; + + // Queries + totalKnowledgeProduced(): number; + totalDecisionsProduced(): number; + averageRoi(): number; + costPerDecision(): number; +} + +export class IntelligenceLedgerFactory { + static createEntry(params: { + id: string; + missionId: string; + budgetId: string; + creditsAllocated: number; + creditsConsumed: number; + observationsProduced: number; + decisionsProduced: number; + businessImpact?: string; + }): IntelligenceLedgerEntry { + const roi = params.creditsConsumed > 0 + ? ((params.observationsProduced + params.decisionsProduced * 10) / params.creditsConsumed) * 100 + : 0; + + return { + ...params, + roi, + createdAt: new Date(), + }; + } +} diff --git a/packages/domain/src/index.ts b/packages/domain/src/index.ts index 9c3ef12d3..4a523966d 100644 --- a/packages/domain/src/index.ts +++ b/packages/domain/src/index.ts @@ -65,6 +65,27 @@ export { DataLifecycleStep, DataLifecycleRules, } from './artifacts/data-lifecycle'; + +// Economic Engine +export { + Credit, + CreditType, + CreditBudget, + CreditFactory, +} from './economic/credit'; + +export { + IntelligenceLedger, + IntelligenceLedgerEntry, + IntelligenceLedgerFactory, +} from './economic/intelligence-ledger'; + +// Mission Engine +export { + KnowledgeGap, + Hotspot, + Contradiction, +} from './mission/knowledge-gap'; export * from './common/enums'; export * from './common/errors'; diff --git a/packages/domain/src/mission/knowledge-gap.ts b/packages/domain/src/mission/knowledge-gap.ts new file mode 100644 index 000000000..6dfe8e037 --- /dev/null +++ b/packages/domain/src/mission/knowledge-gap.ts @@ -0,0 +1,54 @@ +/** + * Knowledge Gap — Missing information that drives missions + * + * ADR-012: Mission Engine + * Knowledge gaps drive new missions, not just customer orders. + */ + +import { GeoLocation } from '../common/value-objects'; + +export interface KnowledgeGap { + readonly id: string; + readonly areaId: string; + readonly location: GeoLocation; + readonly coverage: number; // 0.0 to 1.0 + readonly confidence: number; // 0.0 to 1.0 + readonly priority: 'low' | 'medium' | 'high' | 'critical'; + readonly estimatedValue: number; // In credits + readonly budgetId?: string; + readonly recommendedMissionType: 'inspection' | 'verification' | 'survey'; + readonly createdAt: Date; +} + +export interface Hotspot { + readonly id: string; + readonly areaId: string; + readonly location: GeoLocation; + readonly score: number; // Composite score + readonly factors: { + readonly observationDensity: number; + readonly contradictions: number; + readonly customerRequests: number; + readonly riskTrend: number; + readonly businessValue: number; + }; + readonly recommendedMissions: string[]; // KnowledgeGap IDs +} + +export interface Contradiction { + readonly id: string; + readonly sourceA: { + readonly type: 'observation' | 'register' | 'prediction'; + readonly id: string; + readonly value: string; + }; + readonly sourceB: { + readonly type: 'observation' | 'register' | 'prediction'; + readonly id: string; + readonly value: string; + }; + readonly confidence: number; + readonly potentialValue: number; + readonly suggestedMissionId?: string; + readonly createdAt: Date; +}