boc/docs/design/EPIC-001-First-Verified-Decision.md

# EPIC-001: First Verified Decision

**Goal:** Prove the Intelligence Lab works end-to-end with real data

| | |
|---|---|
| **Epic** | 001 |
| **Status** | READY FOR DEVELOPMENT |
| **Goal** | A pilot can film a real object, upload, get a Decision Case, review AI, correct annotations, see the evidence chain, approve the case, with full version control and traceability |
| **Success** | Complete vertical slice from reality to verified decision |

---

## STOP Rule

**No new pipeline may be implemented until at least 20 real Decision Cases have been produced through the existing pipeline.**

Observe first, improve later.

---

## Field Readiness Gate

Before building any new feature, answer:

| Question | Must Answer |
|----------|-------------|
| Can we use this during a real pilot day? | Yes |
| Will it give us better observation data? | Yes |
| Will it reduce manual work? | Yes |
| Will it improve Decision Cases? | Yes |
| Will it help us validate the model? | Yes |

If **no** on most questions — the feature waits.

---

## Vertical User Journey (Demo)

The complete journey that can be demonstrated in minutes:

```
quiXzoom
↓
Take photo or video
↓
Mission Import
↓
Raw Dataset saved
↓
Dataset Explorer shows mission
↓
AI creates Observation
↓
User corrects if needed
↓
Decision Case created
↓
Decision Viewer shows:
  Observation
  ↓
  Evidence
  ↓
  Finding
  ↓
  Decision
  ↓
  Business Impact
```

If this journey works, the core is proven.

## Sprint Goal

**Every sprint must result in more verified Decision Cases from real pilot missions.**

Keep development close to user reality. Intelligence Lab grows from actual needs, not assumptions.

---

## Stories

### Story 1: Mission Import

**As a** field engineer  
**I want to** upload mission data  
**So that** raw data is stored immutably

```
Video + Images + GPS + EXIF
↓
Raw Dataset (immutable, versioned)
```

**Acceptance:**
- [ ] Upload video and images
- [ ] Extract and display GPS, timestamp, device metadata
- [ ] Store raw data with checksum
- [ ] Show upload progress and confirmation

**Why first:** Proves we can receive real data.

---

### Story 2: Dataset Explorer

**As a** field engineer  
**I want to** browse and search missions  
**So that** I can find specific observations

**Features:**
- List view
- Map view
- Filter by date, location, type
- Search by metadata
- Open mission to see details

**Acceptance:**
- [ ] Browse all missions
- [ ] Filter by date range
- [ ] Filter by location
- [ ] Search by metadata
- [ ] Open mission detail view

**Why second:** Makes data visible and searchable.

---

### Story 3: Annotation Workspace

**As a** field engineer  
**I want to** review and correct AI suggestions  
**So that** observations are accurate

```
Image
↓
AI Detection (bounding box + label + confidence)
↓
Human Review (correct / modify / reject)
↓
Version History
```

**Acceptance:**
- [ ] Show image with AI bounding boxes
- [ ] Display AI label and confidence
- [ ] Allow correction of label
- [ ] Allow adjustment of bounding box
- [ ] Allow rejection of detection
- [ ] Save version history
- [ ] Show before/after comparison

**Why third:** First human-in-the-loop.

---

### Story 4: Decision Case

**As a** field engineer  
**I want to** see the full decision chain  
**So that** I understand why a decision was recommended

```
Observation
↓
Evidence
↓
Finding
↓
Decision
↓
Business Impact
```

**Acceptance:**
- [ ] Display observation with image/video
- [ ] Show evidence (linked observations)
- [ ] Show finding (pattern/conclusion)
- [ ] Show decision (recommended action)
- [ ] Show business impact (risk, cost, time)
- [ ] Allow approval or rejection
- [ ] Show explainability chain (clickable)

**Why fourth:** First verified decision.

---

### Story 5: Replay

**As a** field engineer  
**I want to** replay a mission  
**So that** I can review the entire chain

**V1:** Simple playback — step through the chain  
**Not in V1:** AI comparison, model versioning

```
Mission-001
↓
Step 1: Observation
Step 2: Evidence
Step 3: Finding
Step 4: Decision
Step 5: Business Impact
```

**Acceptance:**
- [ ] Select mission to replay
- [ ] Step through each stage
- [ ] Show data at each stage
- [ ] Navigate forward and backward

**Why fifth:** Proves the chain is reproducible.

---

### Story 6: Session Management

**As a** field engineer  
**I want to** create and manage field sessions  
**So that** missions are organized by location and date

```
Field Session
├── Location: Huddinge
├── Date: 2026-08-14
└── Missions: [Mission-001, Mission-002, ...]
```

**Acceptance:**
- [ ] Create session with location and date
- [ ] List all sessions
- [ ] Open session to see missions

**Why last:** Organizational layer on top of working core.

---

## Golden Mission

**A real mission that never changes, used as regression test.**

```
Golden Mission 001
├── Location: Huddinge
├── Images: 52
├── Videos: 4
├── Observations: 31
└── Verified Decision Cases: 8
```

Every new model runs against the same mission. See immediately if something got better or worse.

## Review (First-Class Object)

Not just Annotation. Full quality flow:

```
Observation
↓
AI
↓
Human Review
↓
Approved / Rejected / Needs More Evidence
```

Makes the entire quality flow traceable.

## Dashboard v1

Extremely simple:

```
FIELD STATUS

Sessions:        3
Missions:        27
Decision Cases:  11
Pending Reviews: 6
Verified Decisions: 8

[Continue Reviewing]
```

Should feel like a work tool, not a BI system.

## Not in First Release

Intentionally postponed:

| Feature | Why Postponed |
|---------|---------------|
| GPU Queue | Not needed for 20 Decision Cases |
| Hyperparameter Search | Not needed for validation |
| Distributed Training | Not needed for MVP |
| Benchmark (15 models) | Not needed for first cases |
| Canary Deployment | Not needed for internal tool |
| Auto Retraining | Not needed until model validated |
| Bias Dashboard | Not needed until diverse data |
| Drift Detection | Not needed until production |

These are important but don't help reach the first verified workflow.

---

## Definition of "First Verified Decision"

**A First Verified Decision is a Decision Case that:**
- Is built on real observation data
- Has been reviewed by a human
- Has a complete evidence chain
- Is fully reproducible from raw data to recommendation

## Definition of Done (Epic)

- [ ] A pilot can film a real object in quiXzoom
- [ ] Upload material to Intelligence Lab
- [ ] Get a Decision Case created automatically
- [ ] Review AI results
- [ ] Correct annotations
- [ ] See full evidence chain
- [ ] Approve Decision Case
- [ ] Everything saved versioned and traceable
- [ ] At least 1 real Decision Case produced
- [ ] Meets "First Verified Decision" definition

---

## Definition of Ready (Next Epic)

**Epic-002 can start when:**
- 20 real Decision Cases exist
- Field Readiness Gate passed
- STOP rule satisfied

---

## Technical Stack (Recommended)

| Layer | Technology | Rationale |
|-------|-----------|-----------|
| Frontend | React + TypeScript (strict) | Type safety, component ecosystem |
| Backend | Node.js + Express + TypeScript | Same language, fast development |
| Database | PostgreSQL | ACID, JSON support, proven |
| Storage | S3/R2 | Immutable object storage |
| Queue | Bull (Redis) | Proven, observable job queue |
| AI | Python microservice | Model inference separate from API |
| Git | All code versioned | Traceability |

---

## Quality Gates

| Gate | Requirement |
|------|-------------|
| **Code** | TypeScript strict, ≥80% test coverage |
| **Security** | No secrets in code, OAuth 2.0 |
| **Audit** | All actions logged, immutable |
| **Deploy** | GitOps, reproducible builds |

---

## ändringshistoria

| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial Epic-001 specification |
| 1.1 | 2026-07-02 | Reordered stories (Mission Import first, Session Management last), added Golden Mission, Review object, Dashboard v1, vertical user journey, First Verified Decision definition |

---

## Vision

**LandveX Intelligence Lab is the internal factory where raw reality is refined into verified Control Intelligence.**

**Architecture Goal:** Every artifact must be traceable backward to its source and forward to its decision.

## Development Rule

**No Story may start with UI. Every Story starts with:**
1. Domain model
2. API
3. Storage
4. Tests
5. UI

This keeps architecture clean and allows testing each part without frontend.

## Story 1: Mission Import — Implementation Plan

### PR-001: Domain Model

```typescript
// Mission
interface Mission {
  id: string;           // mission_20260814_000123
  status: MissionStatus;
  location: Location;
  device: Device;
  createdAt: Date;
  updatedAt: Date;
}

// MissionAsset
interface MissionAsset {
  id: string;           // asset_000456
  missionId: string;
  type: AssetType;      // image | video
  storagePath: string;
  checksum: string;
  sizeBytes: number;
  mimeType: string;
  metadata: AssetMetadata;
  createdAt: Date;
}

// AssetMetadata
interface AssetMetadata {
  exif: ExifData;
  gps: GpsCoordinates;
  device: DeviceInfo;
}

// Upload
interface Upload {
  id: string;
  missionId: string;
  status: UploadStatus;
  progress: number;
  startedAt: Date;
  completedAt?: Date;
}

// Enums
type MissionStatus = 'created' | 'uploading' | 'processing' | 'completed' | 'failed';
type AssetType = 'image' | 'video';
type UploadStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
```

### PR-002: Storage

- Upload to bucket (S3/R2)
- Metadata in PostgreSQL
- Checksums (SHA-256)
- File size
- MIME type
- EXIF extraction
- GPS parsing
- **No AI yet**

### PR-003: API

```
POST   /missions
POST   /missions/{id}/assets
GET    /missions/{id}
GET    /missions
```

### PR-004: Events

```
MissionCreated
↓
AssetUploaded
↓
RawDatasetReady
```

**No pipeline yet. Just events.**

### PR-005: UI

Extremely simple:

```
Mission Import

[Drag files] or [Choose files]

[Upload]

Progress: ████████░░ 80%

Done! Mission mission_20260814_000123 created.
```

### Definition of Done (Story 1)

```
Phone → Video → Upload → Bucket → Metadata → Mission visible in Dataset Explorer
```

This is the first proof.

## ID Convention

**Never UUID in UI. UUID internally.**

| Entity | ID Format | Example |
|--------|-----------|---------|
| Mission | `mission_YYYYMMDD_NNNNNN` | `mission_20260814_000123` |
| Asset | `asset_NNNNNN` | `asset_000456` |
| Observation | `obs_NNNNNN` | `obs_000981` |
| Decision | `decision_NNNNNN` | `decision_000044` |

## Artifact Viewer

When clicking a file, show:

```
Raw Asset
├── Filename: IMG_20260814_143052.jpg
├── Size: 4.2 MB
├── MIME: image/jpeg
├── Hash: sha256:a3f7...
├── GPS: 59.2371, 18.1456
├── EXIF: Device=iPhone14,2, ISO=100, Exposure=1/120s
├── Created: 2026-08-14 14:30:52 UTC
├── Storage: s3://landvex-raw/2026/08/14/mission_20260814_000123/
└── Version: 1
```

Saves enormous time during debugging.

## Status

**READY FOR DEVELOPMENT — PR-001: Domain Model**