docs: Epic-001 v1.3 — 12 architectural adjustments before first line of code

- Session is root (not Mission): Field Session → Mission → Asset → Observation...
- Event Sourcing: never overwrite status, status is projection of history
- Artifact Registry: first-class object with id, type, version, hash, lineage
- Decision Case immutability: Review → Revision → Approved Version (like Git)
- Review Task: Assigned → Reviewed → Approved → Closed
- Processing Graph: nodes not hardcoded chain, swap models without changing rest
- Data Quality as domain: Blur, Duplicate, Bad GPS, Low Resolution, etc.
- Decision Case comparison: show exactly what changed, which evidence, model, human
- Golden Missions + Golden Datasets: two levels
- Domain Event Viewer: timeline (09:42 Mission Created, 09:43 Video Uploaded...)
- KPI: Verified Decision Throughput (verified decisions per day)
- Architecture Principle: 'Produces verified Decision Cases through reproducible
  and traceable pipeline'

Updated PR-001 Domain Model:
- Added FieldSession (root)
- Added Artifact interface
- Added Event sourcing types
- Session ID format: session_YYYYMMDD_NNNNNN
- Updated API to include /sessions endpoints

Rationale: Three fundamental objects (Session, Artifact, Event) make the rest
natural. Scalable, auditable, well-suited for public sector traceability requirements.
This commit is contained in:
Bernt
2026-07-02 13:45:41 +00:00
parent 37ef2f4526
commit 7075cf9ab9
+229 -3
View File
@@ -377,6 +377,19 @@ These are important but don't help reach the first verified workflow.
**Architecture Goal:** Every artifact must be traceable backward to its source and forward to its decision. **Architecture Goal:** Every artifact must be traceable backward to its source and forward to its decision.
**Architecture Principle:**
**LandveX Intelligence Lab does not produce AI results. It produces verified Decision Cases through a reproducible and traceable pipeline.**
## Core Objects
Three fundamental objects:
| Object | Purpose |
|--------|---------|
| **Session** | Organizes field work |
| **Artifact** | Organizes everything produced (video, dataset, models, reports, Decision Cases) |
| **Event** | Organizes history and makes the entire chain reproducible |
## Development Rule ## Development Rule
**No Story may start with UI. Every Story starts with:** **No Story may start with UI. Every Story starts with:**
@@ -388,14 +401,205 @@ These are important but don't help reach the first verified workflow.
This keeps architecture clean and allows testing each part without frontend. This keeps architecture clean and allows testing each part without frontend.
## Hierarchy
```
Field Session
Mission
Mission Asset
Observation
Evidence
Finding
Decision
Action
Outcome
```
**Session is the root.** A pilot day produces many missions.
## Event Sourcing
**Never overwrite status. Status is a projection of history.**
```
MissionCreated
AssetUploaded
AssetValidated
ObservationCreated
EvidenceLinked
DecisionApproved
```
Always replayable.
## Artifact Registry
First-class object. Not just buckets.
```
Artifact
├── id
├── type // video | dataset | model | decision_case | evaluation_report | replay
├── version
├── hash
├── created
├── created_by
├── storage_uri
├── parent
└── lineage
```
Everything becomes traceable.
## Decision Case Immutability
Never modify a Decision Case.
```
Decision Case
Review
Revision
Approved Version
```
Like Git.
## Review Task
```
Review Task
Assigned
Reviewed
Approved
Closed
```
Makes future quality assurance much easier.
## Processing Graph
Not a list of pipelines. Each step is a node.
```
Mission
Dataset
Annotation
Evaluation
Decision
Learning
```
Swap models without changing the rest:
```
YOLO → Grounding DINO → Custom model
```
## Data Quality Domain
```
Quality Issue
├── Blur
├── Duplicate
├── Bad GPS
├── Low Resolution
├── Missing Metadata
├── Wrong Timestamp
└── Occlusion
```
Then: Quality Report.
## Decision Case Comparison
```
Decision A
Decision B
```
Show exactly:
- What changed?
- Which evidence?
- Which confidence?
- Which model?
- Which human?
## Golden Missions & Golden Datasets
| Level | Description |
|-------|-------------|
| **Golden Mission** | Real mission that never changes |
| **Golden Dataset** | Selected observations from Golden Mission |
## Domain Event Viewer
Timeline, not logs:
```
09:42 Mission Created
09:43 Video Uploaded
09:44 GPS Extracted
09:45 AI Analysis
09:47 Human Review
09:50 Decision Approved
```
Incredibly useful.
## KPI: Verified Decision Throughput
Not number of models. Not number of missions.
```
Verified Decision Throughput = Verified decisions per day
```
This is your factory capacity.
## Story 1: Mission Import — Implementation Plan ## Story 1: Mission Import — Implementation Plan
### PR-001: Domain Model ### PR-001: Domain Model
```typescript ```typescript
// FieldSession
interface FieldSession {
id: string; // session_20260814_000001
location: Location;
date: Date;
status: SessionStatus;
missions: string[]; // mission IDs
createdAt: Date;
}
// Mission // Mission
interface Mission { interface Mission {
id: string; // mission_20260814_000123 id: string; // mission_20260814_000123
sessionId: string;
status: MissionStatus; status: MissionStatus;
location: Location; location: Location;
device: Device; device: Device;
@@ -433,9 +637,23 @@ interface Upload {
completedAt?: Date; completedAt?: Date;
} }
// Artifact
interface Artifact {
id: string;
type: ArtifactType;
version: number;
hash: string;
createdBy: string;
storageUri: string;
parentId?: string;
lineage: string[];
}
// Enums // Enums
type SessionStatus = 'planned' | 'active' | 'completed';
type MissionStatus = 'created' | 'uploading' | 'processing' | 'completed' | 'failed'; type MissionStatus = 'created' | 'uploading' | 'processing' | 'completed' | 'failed';
type AssetType = 'image' | 'video'; type AssetType = 'image' | 'video';
type ArtifactType = 'video' | 'dataset' | 'model' | 'decision_case' | 'evaluation_report' | 'replay';
type UploadStatus = 'pending' | 'in_progress' | 'completed' | 'failed'; type UploadStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
``` ```
@@ -453,8 +671,11 @@ type UploadStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
### PR-003: API ### PR-003: API
``` ```
POST /missions POST /sessions
POST /sessions/{id}/missions
POST /missions/{id}/assets POST /missions/{id}/assets
GET /sessions/{id}
GET /sessions
GET /missions/{id} GET /missions/{id}
GET /missions GET /missions
``` ```
@@ -462,10 +683,14 @@ GET /missions
### PR-004: Events ### PR-004: Events
``` ```
SessionCreated
MissionCreated MissionCreated
AssetUploaded AssetUploaded
AssetValidated
RawDatasetReady RawDatasetReady
``` ```
@@ -501,6 +726,7 @@ This is the first proof.
| Entity | ID Format | Example | | Entity | ID Format | Example |
|--------|-----------|---------| |--------|-----------|---------|
| Session | `session_YYYYMMDD_NNNNNN` | `session_20260814_000001` |
| Mission | `mission_YYYYMMDD_NNNNNN` | `mission_20260814_000123` | | Mission | `mission_YYYYMMDD_NNNNNN` | `mission_20260814_000123` |
| Asset | `asset_NNNNNN` | `asset_000456` | | Asset | `asset_NNNNNN` | `asset_000456` |
| Observation | `obs_NNNNNN` | `obs_000981` | | Observation | `obs_NNNNNN` | `obs_000981` |