boc/docs/design/DECISION_MODEL_v1.0.md

DECISION MODEL v1.0

The Core Product of Landvex

Version	1.0
Status	DRAFT
Scope	All Landvex decisions, dashboards, reports, APIs

---

The Six Layers

Layer 1: Reality
    (sensors, mobile, video, GIS, drones)
    ↓
Layer 2: Observation
    ("crack detected", "road surface degraded")
    ↓
Layer 3: Evidence
    (linked observations with context)
    ↓
Layer 4: Finding
    ("area has deteriorated since last inspection")
    ↓
Layer 5: Decision
    ("prioritize inspection within 14 days")
    ↓
Layer 6: Business Impact
    ("risk reduced", "cost avoided", "revenue created")

---

Layer 1: Reality

Input sources:

• Mobile phones (quiXzoom)
• Drones
• Fixed cameras
• Sensors
• GIS data
• Satellite imagery

Principle: Reality is the only source of truth.

---

Layer 2: Observation

Definition: A single recorded fact from reality.

Example:

Observation:
- Type: "crack"
- Location: [lat, lng]
- Timestamp: 2026-07-02T10:00:00Z
- Source: quiXzoom mobile
- Media: [photo_url, video_url]
- Observation Confidence: 0.94

---

Layer 3: Evidence

Definition: Linked observations with context, forming a body of proof.

Example:

Evidence:
- Description: "Multiple cracks observed in Sector 7"
- Observations: [observation_1, observation_2, observation_3]
- Evidence Strength: 0.91
- Consistency: "All observations confirm degradation"
- Time Span: "2026-06-15 to 2026-07-02"

Layer 4: Finding

Definition: A pattern or conclusion derived from evidence.

Example:

Finding:
- Description: "Road surface has degraded 15% since last inspection"
- Area: "Nacka Municipality, Sector 7"
- Evidence: [evidence_1, evidence_2]
- Finding Confidence: 0.87
- Trend: "deteriorating"

---

Layer 5: Decision

Definition: An evidence-backed recommended action.

Decision Object

Every decision must contain:

#	Field	Description	Example
1	Decision	What should the user decide?	"Prioritize inspection"
2	Why	Why does the system recommend this?	"Road surface degraded 15%"
3	Evidence	What observations support this?	[evidence_1, evidence_2]
4	Confidence	How certain is the model?	See Confidence Model below
5	Consequence	What happens if nothing is done?	"Risk of accident increases"
6	Action	What is the next step?	"Schedule inspection"
7	Business Impact	What does this mean economically/operationally?	See Business Impact Model below

Confidence Model

Dimension	Description	Example
Observation Confidence	How certain is the detection?	"94% — clear visual evidence"
Evidence Strength	How strongly does evidence support the conclusion?	"91% — three consistent observations"
Recommendation Confidence	How certain is the recommendation?	"87% — historical data supports this action"

Explainability

Every Decision Card must be explorable:

Decision
    ↓ (click)
Finding
    ↓ (click)
Evidence
    ↓ (click)
Observations
    ↓ (click)
Reality

The user must be able to click all the way back to source material.

---

Layer 6: Business Impact

Definition: The measurable effect of the decision on the business.

Type	Metric	Example
Risk	Probability × Severity	"High — accident risk 12% → 3%"
Cost	Currency	"$50,000 in emergency repairs avoided"
Time	Duration	"Action required within 14 days"
Opportunity	Business value	"Plan maintenance with nearby works"

---

Decision Card

Visual representation:

┌─────────────────────────────────────┐
│ Area Score: 87                      │
│ ▼                                   │
│                                     │
│ 3 Important Decisions               │
│ ┌─────────────────────────────────┐ │
│ │ ⚠️ Road surface degraded        │ │
│ │    Confidence: 87%              │ │
│ │    Priority: High               │ │
│ │    Recommend: Inspect in 14d    │ │
│ │    If ignored: Safety risk ↑    │ │
│ │    Next step: Schedule now      │ │
│ │    Evidence: 12 observations    │ │
│ └─────────────────────────────────┘ │
│                                     │
│ Map                                 │
│                                     │
│ Evidence                            │
│                                     │
│ History                             │
└─────────────────────────────────────┘

---

Verification

For every decision:

• Decision — what should the user decide?
• Why — why does the system recommend this?
• Evidence — what observations support this?
• Confidence — how certain is the model? (observation, evidence, recommendation)
• Consequence — what happens if nothing is done?
• Action — what is the next step?
• Business Impact — what does this mean economically/operationally?
• Explainability — can the user click back to source material?

Validation Scenarios

Before freezing Decision Model v1.0, validate against three real scenarios:

Scenario 1: Road Crack

Layer	Example
Reality	Mobile photo of road crack
Observation	"Crack detected, 15cm width"
Evidence	3 observations of cracks in same area
Finding	"Road surface degraded 15% since last inspection"
Decision	"Prioritize inspection within 14 days"
Business Impact	Risk: High, Cost: $50k avoided, Time: 14 days, Opportunity: Plan with nearby works

Scenario 2: Damaged Facade

Layer	Example
Reality	Drone video of building facade
Observation	"Facade panel loose, 30cm displacement"
Evidence	2 observations + weather data
Finding	"Facade integrity compromised, risk of falling debris"
Decision	"Immediate safety inspection required"
Business Impact	Risk: Critical, Cost: $200k liability, Time: 24 hours, Opportunity: Prevent injury

Scenario 3: Broken Road Sign

Layer	Example
Reality	Mobile photo of damaged sign
Observation	"Stop sign damaged, 50% visibility"
Evidence	1 observation + traffic data
Finding	"Traffic control compromised at intersection"
Decision	"Replace sign within 48 hours"
Business Impact	Risk: Medium, Cost: $5k fine avoided, Time: 48 hours, Opportunity: Standard replacement

Pass criteria: Same Decision Object works for all three without modification.

---

Relationship to Dashboard

Dashboard is not: 120 widgets Dashboard is: Decision Card visualization

Area Score
    ↓
Top 3 Decisions
    ↓
Map
    ↓
Evidence
    ↓
History

---

ändringshistoria

Version	Datum	Beskrivning
1.0	2026-07-02	Initial decision model with six layers, evidence-backed decisions, explainability, confidence model, validation scenarios

---

STATUS

DRAFT — Awaiting validation against three scenarios