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:
@@ -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` |
|
||||||
|
|||||||
Reference in New Issue
Block a user