boc/quixzoom-capture-pipeline/README-ARCHITECTURE.md

# QUIXZOOM Arkitektur — Komplett System

## Utvecklingsordning (Eriks prioritering)

```
1. Object Identity Engine     (deduplicering och objektmatchning)
2. Persistenslager            (PostgreSQL + PostGIS + Neo4j)
3. Observation Engine
4. Evidence Engine
5. Temporal Engine
6. Mission Generator
7. Adaptive AI
8. Developer Visualization
9. GraphQL API
```

---

## Komponenter

### 1. Object Identity Engine ✅

**Fil:** `identity-engine/identity.js`

**Funktion:** Avgör om två observationer avser samma fysiska objekt.

**Signaler:**
- GPS (med accuracy)
- Kameravinkel (kompass, pitch, roll)
- 3D-position
- Visuell signatur (perceptual hash)
- Storlek
- Närliggande objekt (spatial context)
- Historik
- Sannolikhetsmodell

**Exempel:**
```javascript
const result = await engine.matchObservation(observation);
// Result: MATCHED (confidence: 94.2%)
// Breakdown: { gps: 0.98, visual: 0.85, angle: 0.72, ... }
```

---

### 2. Persistenslager ✅

#### PostgreSQL + PostGIS
**Fil:** `persistence/postgres-schema.sql`

**Tabeller:**
- `zoomers` — Zoomer-profiler
- `areas` — Områden med spatiala bounds
- `observations` — Observationer med GPS
- `objects` — Urban objects
- `evidence` — Bevis
- `temporal_records` — Historik
- `missions` — Uppdrag
- `sensor_logs` — Sensor-data
- `events` — Event sourcing

**Spatiala index:**
```sql
CREATE INDEX idx_observations_location ON observations USING GIST(location);
CREATE INDEX idx_objects_location ON objects USING GIST(location);
```

#### Neo4j
**Fil:** `persistence/neo4j-schema.cypher`

**Noder:** Object, Observation, Evidence, Area, Zoomer, Mission

**Relationer:**
```cypher
(:Object)-[:OBSERVED_IN]->(:Observation)
(:Object)-[:SUPPORTED_BY]->(:Evidence)
(:Object)-[:NEAR {distance: 5}]->(:Object)
(:Object)-[:PART_OF]->(:Object)
(:Object)-[:REPLACED_BY]->(:Object)
```

#### Event Store
**Fil:** `persistence/event-store.js`

**Event-flöde:**
```
ObservationCreated
  ↓
ObservationValidated
  ↓
EvidenceAdded
  ↓
ObjectUpdated
  ↓
MissionGenerated
  ↓
LearningQueueUpdated
```

**Fördelar:**
- Hela stadens historik kan spelas upp igen
- Algoritmer kan förbättras retroaktivt
- Full audit trail

---

### 3. Observation Engine ✅

**Fil:** `urban-knowledge-graph/ukg.js`

**Tre lager:**
1. **Observation Layer** — Strukturerade observationer (inte bilder)
2. **Evidence Layer** — Ett objekt, hundra bevis
3. **Temporal Layer** — Förändring över tid

**Exempel:**
```javascript
const observation = {
  id: 'obs_482917',
  object: {
    type: 'street_lamp',
    attributes: {
      material: 'steel',
      height: 7.8,
      paint: 'grey',
      rust: true,
      lean: 4,
      light: 'broken'
    }
  },
  location: { lat: 13.725, lng: 100.555 },
  confidence: 0.94,
  verified: false
};
```

---

### 4. Evidence Engine ✅

**Fil:** `urban-knowledge-graph/ukg.js`

**Samma gatlykta i hundra videor = ETT objekt:**

```
Street Lamp #1293
├── Video A, Frame 342 (Zoomer 001, reliability: 0.85)
├── Video B, Frame 91 (Zoomer 002, reliability: 0.80)
├── QUIXZOOM Capture (Zoomer 003, reliability: 0.90)
├── Inspector Capture (Municipality, reliability: 0.95)
└── Municipality Capture (Official, reliability: 0.98)
```

---

### 5. Temporal Engine ✅

**Fil:** `urban-knowledge-graph/ukg.js`

**Förändring över tid:**

| Datum | Händelse | Ändringar |
|-------|----------|-----------|
| 2026-06-01 | Initial observation | — |
| 2026-08-12 | Tilt detected | lean: 0° → 2° |
| 2026-09-20 | Corrosion increasing | rust: no → yes, light: working → flickering |
| 2026-10-11 | Light broken | light: flickering → broken |
| 2026-11-02 | Replaced | status: repaired |

---

### 6. Mission Generator ✅

**Fil:** `fleet-intelligence/coordinator.js`

**Uppdragstyper:**
- `verify` — Verifiera osäker observation
- `explore` — Utforska kunskapsgap
- `document` — Dokumentera specifikt objekt
- `diversify` — Filma vid annan tid/vinkel

**Exempel:**
```javascript
// Zoomer A dokumenterar Sukhumvit
// Zoomer B verifierar misstänkt skada
// Zoomer C filma nattetid
// Zoomer D annan kameravinkel
```

---

### 7. Adaptive AI ✅

**Fil:** `app/guided-capture.js`, `app/active-learning.js`

**Fyra nivåer:**
1. **Recording** — Basinsamling
2. **Guided** — AI ger instruktioner
3. **Mission** — Specifika uppgifter
4. **Adaptive** — AI planerar nästa observation

**Nivå 5 — Fleet Intelligence:**
- Optimerar hela flottan
- Tilldelar uppdrag baserat på position
- Balanserar täckning

---

### 8. Developer Visualization ✅

**Fil:** `visualization/dev-dashboard.html`

**Vy:**
- Alla observerade objekt
- Kunskapsgap
- Osäkra observationer
- Väntande verifieringar
- Aktiva Zoomers
- AI:s rekommenderade nästa uppdrag

---

### 9. GraphQL API (senare)

**Planerat:**
```graphql
type Object {
  id: ID!
  type: String!
  location: GeoPoint!
  attributes: JSON
  observations: [Observation!]!
  evidence: [Evidence!]!
  temporal: [TemporalRecord!]!
  relations: [Relation!]!
}

query {
  objects(area: "bangkok", type: "street_lamp") {
    id
    location
    confidence
    verificationStatus
  }
}
```

---

## Dataflöde

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   iOS App   │────▶│  WebSocket  │────▶│   Backend   │
│  (Capture)  │     │   Server    │     │  (Node.js)  │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                    ┌──────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────┐
│              URBAN KNOWLEDGE GRAPH                       │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │ Observation │  │  Evidence   │  │  Temporal   │     │
│  │   Layer     │  │   Layer     │  │   Layer     │     │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │
│         │                │                │             │
│         └────────────────┼────────────────┘             │
│                          │                              │
│                    ┌─────┴─────┐                        │
│                    │  Object   │                        │
│                    │  Entity   │                        │
│                    └─────┬─────┘                        │
│                          │                              │
│         ┌────────────────┼────────────────┐             │
│         ▼                ▼                ▼             │
│    ┌─────────┐     ┌─────────┐     ┌─────────┐        │
│    │PostgreSQL│     │  Neo4j  │     │  Event  │        │
│    │+PostGIS │     │ (Graph) │     │  Store  │        │
│    └─────────┘     └─────────┘     └─────────┘        │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                    AI & ANALYTICS                        │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Object    │  │   Active    │  │   Fleet     │     │
│  │  Identity   │  │  Learning   │  │Coordinator │     │
│  │   Engine    │  │             │  │             │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                    VISUALISERING                         │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Dev       │  │   Admin     │  │   GraphQL   │     │
│  │ Dashboard   │  │   Panel     │  │    API      │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
└─────────────────────────────────────────────────────────┘
```

---

## Filstruktur

```
quixzoom-capture-pipeline/
├── identity-engine/
│   └── identity.js              # Object Identity Engine
├── persistence/
│   ├── event-store.js           # Event Sourcing
│   ├── postgres-schema.sql      # PostgreSQL + PostGIS
│   └── neo4j-schema.cypher      # Neo4j Graph
├── urban-knowledge-graph/
│   ├── ukg.js                   # Urban Knowledge Graph
│   └── README-UKG.md
├── fleet-intelligence/
│   └── coordinator.js           # Fleet Coordinator
├── value-score/
│   └── calculator.js            # Data Value Score
├── app/
│   ├── guided-capture.js        # 4-nivå insamling
│   └── active-learning.js       # Information gain
├── websocket/
│   └── server.js                # WebSocket Server
├── ios/
│   └── QuixZoomCapture/         # iOS App (Swift)
├── visualization/
│   └── dev-dashboard.html       # Developer Dashboard
└── README-ARCHITECTURE.md       # Denna fil
```

---

## Nästa steg

1. **Deploya PostgreSQL + PostGIS**
2. **Deploya Neo4j**
3. **Integrera Object Identity Engine med UKG**
4. **Bygg backend-API**
5. **Testa med riktig data från Bangkok**

---

*LandveX Inc. — Urban Knowledge Graph: Den verkliga hjärnan i QUIXZOOM.*