diff --git a/docs/design/PR-001-DOMAIN-MODEL.md b/docs/design/PR-001-DOMAIN-MODEL.md index 2d6bb8bb2..04fdd44bd 100644 --- a/docs/design/PR-001-DOMAIN-MODEL.md +++ b/docs/design/PR-001-DOMAIN-MODEL.md @@ -14,6 +14,68 @@ **This package describes the LandveX domain model. It contains no dependencies to database, HTTP, cloud storage, or AI frameworks. It defines only the language, objects, and rules that the rest of the platform builds upon.** +## Three Rules + +### Rule 1: Domain knows nothing about AI + +**No AI-specific objects in domain:** +- ❌ `AIObservation` +- ❌ `YOLODetection` +- ❌ `GeminiResult` +- ❌ `ClaudeAnalysis` + +**Domain only knows:** +- ✅ `Observation` +- ✅ `Evidence` +- ✅ `Finding` +- ✅ `Decision` +- ✅ `Review` +- ✅ `Outcome` + +If we switch from YOLO to a custom model in five years, the domain does not change. + +### Rule 2: Everything is an Artifact + +`Artifact` is a common contract for everything produced: + +``` +Artifact +├── Image +├── Video +├── Dataset +├── Annotation +├── Model +├── Evaluation +├── DecisionCase +├── Report +└── ExperienceInsight +``` + +All artifacts share: +- `id` +- `version` +- `hash` +- `lineage` +- `createdAt` +- `createdBy` +- `storageUri` + +This makes the entire platform consistent. + +### Rule 3: All decisions are reproducible + +Every Decision Case must answer: +- Which observations were used? +- Which evidence was used? +- Which model? +- Which model version? +- Which rules? +- Who reviewed? +- When? +- Which version was approved? + +If any question cannot be answered, the Decision Case is incomplete. + --- ## Package Structure @@ -286,7 +348,7 @@ interface DecisionApproved { - Must have at least one Observation - Must have at least one Evidence - Must have exactly one Decision -- Cannot be Approved without Review +- Must have at least one Review before Approved - Immutable once created — revisions create new versions ### Artifact @@ -296,8 +358,30 @@ interface DecisionApproved { - Version is incremented on each change - Parent reference creates lineage chain +### Review + +- Must belong to exactly one Decision +- Must have a reviewer +- Must have a status (Assigned, In Review, Approved, Rejected, Needs More Evidence) +- Approved requires at least one completed review + --- +## Capability Tags + +For developers — not users. Makes dependencies clear as platform grows. + +``` +Observation +├── Capabilities: [Detection, Vision, GPS, Image] + +Decision +├── Capabilities: [Decision, Recommendation, Business] + +Artifact +├── Capabilities: [Storage, Versioning, Lineage] +``` + ## TypeScript Interfaces ```typescript @@ -331,7 +415,7 @@ interface DecisionCase { evidenceIds: string[]; findingId: string; decisionId: DecisionId; - reviewId: string; + reviewIds: string[]; status: 'pending' | 'under_review' | 'approved' | 'rejected'; version: number; createdAt: Date; @@ -525,11 +609,11 @@ The concepts `Session`, `Mission`, `Artifact`, `Observation`, `Evidence`, `Findi --- -## Future Module: Human Intelligence (Not in Epic-001) +## Future Module: Experience Intelligence (Not in Epic-001) **Positioning:** External Intelligence Module, not part of core domain. -**Why separate:** Customer satisfaction data is not an observation from reality like a road crack. It is **context** that can influence priorities and decisions. +**Why separate:** Stakeholder feedback is not an observation from reality like a road crack. It is **context** that can influence priorities and decisions. **Architecture:** ``` @@ -541,21 +625,25 @@ Reality Intelligence ├── Operational Intelligence ← Future │ SLA, Tickets, Costs, Times │ -├── Human Intelligence ← Future module -│ Customer satisfaction +├── Experience Intelligence ← Future module │ Citizen surveys +│ Customer satisfaction +│ Field technician feedback +│ Contractor experience +│ Service desk data │ NPS, Complaints, Feedback │ └── External Intelligence ← Future │ Weather, Traffic, Demographics ``` -**Human Insight Artifact:** +**Experience Insight Artifact:** ``` -Human Insight +Experience Insight ├── Source: "Kommunenkät 2026" ├── Geography: [Stockholm, Nacka] ├── Period: "Q2 2026" +├── Stakeholders: [Citizens, Field Technicians, Contractors] ├── Metrics: │ ├── CSAT: 4.2 │ ├── NPS: 62 @@ -565,11 +653,11 @@ Human Insight **Usage:** Linked to Area or Decision Case, but never mixed with raw field observations. -**Decision Case with Human Intelligence:** +**Decision Case with Experience Intelligence:** ``` Observation: "Crack on main street" Evidence: [Image, Video, History, GIS] -Human Intelligence: "Many complaints last 30 days, low satisfaction index" +Experience Intelligence: "Many complaints last 30 days, low satisfaction index" Decision: "Prioritize repair within 14 days" Business Impact: "Reduced risk, lower future cost, improved citizen satisfaction" ``` @@ -601,3 +689,15 @@ Freedom to change technology without touching core model. ## Status **READY FOR IMPLEMENTATION** + +**Merge Criteria:** +- [ ] Developer can read model and understand domain language +- [ ] AI engineer can read model and understand domain language +- [ ] Product owner can read model and understand domain language +- [ ] Domain expert can read model and understand domain language +- [ ] All use same terms for `Observation`, `Evidence`, `Decision`, `Outcome` +- [ ] No AI-specific objects in domain +- [ ] All objects are Artifacts +- [ ] All decisions are reproducible +- [ ] Domain invariants documented +- [ ] Capability tags defined