boc/quixzoom-capture-pipeline/uios/UIOS-v1.2-MULTI-CITY.md

# UIOS v1.2 – Multi-City Deployment

**Version:** 1.2.0  
**Date:** 2026-06-28  
**Status:** Specification  
**Previous:** UIOS v1.1 (Real World Validation)

---

## Overview

UIOS v1.2 scales from single-city validation to multi-city deployment. After proving the system works in Bangkok, we deploy to 3+ cities simultaneously.

> "One city proves the concept. Three cities prove the platform."

---

## Goals

### 1. Multi-City Infrastructure

**Cities:**

| City | Country | Type | Climate | Priority |
|------|---------|------|---------|----------|
| Bangkok | TH | Tropical megacity | Tropical | ✅ Active |
| Torrevieja | ES | Mediterranean coastal | Mediterranean | 🎯 Target |
| Stockholm | SE | Nordic capital | Temperate | 🎯 Target |

**Infrastructure per city:**
- PostgreSQL database (city-specific schema)
- Neo4j graph (city-specific graph)
- S3 bucket (city-specific prefix)
- API endpoint (city-specific routing)

### 2. Cross-City Learning

**Reference City concept:**
- Each city becomes a reference for its climate/type
- Models trained on Bangkok (tropical) transfer to other tropical cities
- Models trained on Torrevieja (Mediterranean) transfer to similar climates

**Learning transfer:**
```
Bangkok (tropical) ──► Singapore, Jakarta, Manila
Torrevieja (mediterranean) ──► Barcelona, Nice, Athens
Stockholm (nordic) ──► Oslo, Helsinki, Copenhagen
```

### 3. Unified Dashboard

**Single pane of glass:**
- All cities on one map
- Comparative analytics
- Cross-city missions
- Global coverage tracking

---

## Architecture Changes

### v1.1 (Single City)
```
Bangkok ──► Database ──► API ──► Dashboard
```

### v1.2 (Multi-City)
```
Bangkok ──┐
Torrevieja ─┼──► City Router ──► Unified API ──► Global Dashboard
Stockholm ──┘
```

### City Router

```typescript
interface CityRouter {
  route(request: Request): CityConfig {
    // Route by:
    // - Request header: X-City-ID
    // - GPS coordinates
    // - User preference
    // - Default: nearest city
  }
}
```

---

## Deployment Plan

### Phase 1: Torrevieja (Week 1-2)

**Preparation:**
- [ ] Recruit 3 Zoomers in Torrevieja
- [ ] Adapt onboarding to Spanish
- [ ] Configure Mediterranean object types
- [ ] Set up S3 prefix: `s3://landvex-prod/torrevieja/`

**Launch:**
- [ ] Deploy API endpoint: `/api/v1/torrevieja/`
- [ ] Start data collection
- [ ] Daily sync with Bangkok team

### Phase 2: Stockholm (Week 3-4)

**Preparation:**
- [ ] Recruit 3 Zoomers in Stockholm
- [ ] Adapt onboarding to Swedish
- [ ] Configure Nordic object types
- [ ] Set up S3 prefix: `s3://landvex-prod/stockholm/`

**Launch:**
- [ ] Deploy API endpoint: `/api/v1/stockholm/`
- [ ] Start data collection
- [ ] Weekly all-hands with Bangkok + Torrevieja

### Phase 3: Integration (Week 5-6)

**Unified Dashboard:**
- [ ] Global map with all cities
- [ ] Comparative analytics
- [ ] Cross-city learning metrics

**Model Transfer:**
- [ ] Test Bangkok model on Torrevieja data
- [ ] Test Bangkok model on Stockholm data
- [ ] Measure transfer learning accuracy

---

## Data Model Changes

### City-Specific Schema

```sql
-- Each city gets its own schema
CREATE SCHEMA bangkok;
CREATE SCHEMA torrevieja;
CREATE SCHEMA stockholm;

-- Tables per schema
bangkok.objects
bangkok.observations
bangkok.events

torrevieja.objects
torrevieja.observations
torrevieja.events
```

### Global Tables

```sql
-- Cross-city tables
CREATE TABLE global.zoomers (
  id TEXT PRIMARY KEY,
  name TEXT,
  city_id TEXT REFERENCES global.cities(id),
  level INTEGER,
  status TEXT
);

CREATE TABLE global.cities (
  id TEXT PRIMARY KEY,
  name TEXT,
  country TEXT,
  type TEXT,
  climate TEXT,
  location GEOGRAPHY(POINT)
);
```

---

## API Changes

### City-Specific Endpoints

```
GET /api/v1/bangkok/objects
GET /api/v1/torrevieja/objects
GET /api/v1/stockholm/objects
```

### Global Endpoints

```
GET /api/v1/cities                    # List all cities
GET /api/v1/cities/bangkok            # City details
GET /api/v1/cities/bangkok/stats      # City statistics
GET /api/v1/global/coverage           # Global coverage map
GET /api/v1/global/comparison         # City comparison
```

---

## Zoomer Changes

### Multi-City Zoomers

**Local Zoomers:**
- Work in one city
- Know local area
- Local language

**Traveling Zoomers:**
- Work in multiple cities
- Higher compensation
- Cross-city verification

### Regional Coordinators per City

| City | Coordinator | Zoomers |
|------|-------------|---------|
| Bangkok | Somchai | 3 |
| Torrevieja | TBD | 3 |
| Stockholm | TBD | 3 |

---

## Success Metrics

### Per City

| Metric | Bangkok | Torrevieja | Stockholm |
|--------|---------|------------|-----------|
| Zoomers | 3 | 3 | 3 |
| Observations | 1,000+ | 500+ | 500+ |
| Object types | 6 | 6 | 6 |
| Coverage score | >60% | >50% | >50% |

### Global

| Metric | Target |
|--------|--------|
| Total cities | 3 |
| Total zoomers | 9 |
| Total observations | 2,000+ |
| Cross-city model transfer | >70% accuracy |
| Unified dashboard | ✅ |

---

## Timeline

| Week | Activity |
|------|----------|
| 1 | Torrevieja recruitment |
| 2 | Torrevieja launch |
| 3 | Stockholm recruitment |
| 4 | Stockholm launch |
| 5 | Integration, dashboard |
| 6 | Model transfer testing |
| 7 | Review, optimization |
| 8 | Plan v1.3 |

---

## Risks

| Risk | Mitigation |
|------|------------|
| Language barriers | Local onboarding, translated materials |
| Different object types | Flexible taxonomy per city |
| Climate differences | Reference city model transfer |
| Time zone coordination | Async communication, weekly sync |

---

## v1.3 Preview

- **v1.3:** Customer API launch
- **v1.4:** Model marketplace
- **v1.5:** Autonomous mission planning
- **v2.0:** Global scale

---

**End of v1.2 Specification**