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
@@ -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 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
|
||||
|
||||
**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.
|
||||
|
||||
## 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
|
||||
|
||||
### PR-001: Domain Model
|
||||
|
||||
```typescript
|
||||
// FieldSession
|
||||
interface FieldSession {
|
||||
id: string; // session_20260814_000001
|
||||
location: Location;
|
||||
date: Date;
|
||||
status: SessionStatus;
|
||||
missions: string[]; // mission IDs
|
||||
createdAt: Date;
|
||||
}
|
||||
|
||||
// Mission
|
||||
interface Mission {
|
||||
id: string; // mission_20260814_000123
|
||||
sessionId: string;
|
||||
status: MissionStatus;
|
||||
location: Location;
|
||||
device: Device;
|
||||
@@ -433,9 +637,23 @@ interface Upload {
|
||||
completedAt?: Date;
|
||||
}
|
||||
|
||||
// Artifact
|
||||
interface Artifact {
|
||||
id: string;
|
||||
type: ArtifactType;
|
||||
version: number;
|
||||
hash: string;
|
||||
createdBy: string;
|
||||
storageUri: string;
|
||||
parentId?: string;
|
||||
lineage: string[];
|
||||
}
|
||||
|
||||
// Enums
|
||||
type SessionStatus = 'planned' | 'active' | 'completed';
|
||||
type MissionStatus = 'created' | 'uploading' | 'processing' | 'completed' | 'failed';
|
||||
type AssetType = 'image' | 'video';
|
||||
type ArtifactType = 'video' | 'dataset' | 'model' | 'decision_case' | 'evaluation_report' | 'replay';
|
||||
type UploadStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
|
||||
```
|
||||
|
||||
@@ -453,8 +671,11 @@ type UploadStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
|
||||
### PR-003: API
|
||||
|
||||
```
|
||||
POST /missions
|
||||
POST /sessions
|
||||
POST /sessions/{id}/missions
|
||||
POST /missions/{id}/assets
|
||||
GET /sessions/{id}
|
||||
GET /sessions
|
||||
GET /missions/{id}
|
||||
GET /missions
|
||||
```
|
||||
@@ -462,10 +683,14 @@ GET /missions
|
||||
### PR-004: Events
|
||||
|
||||
```
|
||||
SessionCreated
|
||||
↓
|
||||
MissionCreated
|
||||
↓
|
||||
↓
|
||||
AssetUploaded
|
||||
↓
|
||||
↓
|
||||
AssetValidated
|
||||
↓
|
||||
RawDatasetReady
|
||||
```
|
||||
|
||||
@@ -501,6 +726,7 @@ This is the first proof.
|
||||
|
||||
| Entity | ID Format | Example |
|
||||
|--------|-----------|---------|
|
||||
| Session | `session_YYYYMMDD_NNNNNN` | `session_20260814_000001` |
|
||||
| Mission | `mission_YYYYMMDD_NNNNNN` | `mission_20260814_000123` |
|
||||
| Asset | `asset_NNNNNN` | `asset_000456` |
|
||||
| Observation | `obs_NNNNNN` | `obs_000981` |
|
||||
|
||||
Reference in New Issue
Block a user