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 diverse scenarios:

Scenario 1: Road Crack (Maintenance)

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

Decision type: Maintenance — "Repair now or later?"

Scenario 2: Damaged Facade (Safety)

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

Decision type: Safety — "Act immediately?"

Scenario 3: Broken Road Sign (Compliance)

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

Decision type: Compliance — "Does this violate requirements?"

Scenario 4: Vegetation Blocking Sight (Risk Reduction)

Layer	Example
Reality	Mobile photo of overgrown vegetation
Observation	"Vegetation 80cm high, blocking sight line"
Evidence	2 observations over 3 months + growth trend
Finding	"Gradual degradation of sight lines at intersection"
Decision	"Schedule vegetation removal within 30 days"
Business Impact	Risk: Medium, Cost: $15k avoided, Time: 30 days, Opportunity: Coordinate with seasonal maintenance

Decision type: Risk reduction — "Gradual deterioration requiring planned action"

Scenario 5: Parking Area Wear (Investment Priority)

Layer	Example
Reality	Multiple mobile photos of parking area
Observation	"Surface wear, potholes, faded markings"
Evidence	5 observations + usage data + weather exposure
Finding	"Multiple minor issues collectively indicate need for resurfacing"
Decision	"Include in next year's maintenance budget"
Business Impact	Risk: Low, Cost: $100k investment, Time: 6 months, Opportunity: Improve user satisfaction

Decision type: Investment priority — "Multiple small observations motivating larger decision"

Scenario 6: Cosmetic Scratch (No Action)

Layer	Example
Reality	Mobile photo of road sign
Observation	"Minor cosmetic scratches, 5% of surface"
Evidence	1 observation, no functional impact
Finding	"Normal wear and tear, no safety or compliance impact"
Decision	"No action recommended. Continue monitoring."
Business Impact	Risk: None, Cost: $0, Time: Annual review, Opportunity: None

Decision type: No action — "Conscious decision to wait"

Scenario 7: Mixed Evidence Sources

Layer	Example
Reality	Mobile photo + sensor data + weather API
Observation	"Water pooling, 3cm depth, after rainfall"
Evidence	Photo + rain sensor + historical flooding data + GIS topography
Finding	"Drainage inadequate, recurring flooding risk"
Decision	"Inspect drainage system, prioritize if flooding recurs"
Business Impact	Risk: Medium, Cost: $30k avoided, Time: 14 days, Opportunity: Permanent fix during dry season

Decision type: Complex — "Multiple evidence sources converging"

---

Decision Invariance Test

For each scenario, verify:

Question	Pass Criteria
Same Decision Object structure?	All 7 fields present
Any field added?	No new fields needed
Any field always empty?	No field unused across scenarios
Any field meaning different things?	Each field has consistent meaning

Fail criteria: If any question answers "no", the model needs revision.

---

Evidence Variation Test

Evidence Type	Scenario	Pass
Single image	Scenario 3	✅
Multiple images	Scenario 1	✅
Video + GPS	Scenario 2	✅
Historical observations	Scenario 4	✅
External data (weather, traffic)	Scenario 7	✅
Mixed sources	Scenario 7	✅

Pass criteria: Decision Object structure unchanged regardless of evidence type.

---

Decision Quality Gate

Before displaying any decision to the user:

• At least one verifiable evidence chain exists
• Confidence is motivated (not arbitrary)
• Recommended action exists OR conscious "no action" decision
• Explainability chain works (can click back to observations)

---

Pass Criteria

Decision Model v1.0 is validated when:

1. All 7 scenarios produce valid Decision Objects
2. Decision Invariance Test passes
3. Evidence Variation Test passes
4. Decision Quality Gate passes for all scenarios
5. "No action" scenario works correctly

Status: ⏳ Pending validation

---

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