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**