# 01 - System Overview (Master Book 2.0.1)

**Version:** 2.0.1  
**Generated:** 2026-03-26  
**Auditor:** Projekt Manager Gemini  
**Status:** 70% Complete (Backend/DB Stable, Frontend/Testing Incomplete)

---

## 🏛️ Architectural Foundation

### Core Technology Stack
- **Backend Framework:** FastAPI 2.0+ (Python, Async/Await)
- **Database:** PostgreSQL 15+ with PostGIS extension
- **ORM:** SQLAlchemy 2.0+ (AsyncPG driver)
- **Frontend:** Vue 3 + Vite (Admin), Nuxt.js (Public)
- **Containerization:** Docker Compose V2 (30+ containers)
- **Message Queue:** Redis (caching, sessions, pub/sub)
- **Object Storage:** MinIO (S3-compatible)
- **AI/OCR:** Hybrid AI Gateway (Ollama 14B Qwen + Llama Vision + Gemini/Groq fallback)

### Domain-Driven Design Schemas
The system implements strict domain separation across 19 PostgreSQL schemas:

| Schema | Table Count | Domain Responsibility | Status |
|--------|-------------|----------------------|--------|
| `identity` | 7 | Person/User dual model, authentication | ✅ Active |
| `finance` | 6 | Triple Wallet economy, ledger, transactions | ✅ Active |
| `vehicle` | 25 | Assets, definitions, history, specifications | ✅ Active |
| `marketplace` | 12 | Service providers, profiles, bookings | ✅ Active |
| `gamification` | 11 | XP, badges, leaderboards, competitions | ✅ Active |
| `fleet` | 6 | Fleet management, assignments | ✅ Active |
| `system` | 15 | Parameters, configurations, translations | ✅ Active |
| `audit` | 5 | Process logs, security events | ✅ Active |
| `data` | 0 | Reserved for external data ingestion | 🔄 Planned |
| `tiger` | 34 | PostGIS extension tables (geospatial) | ✅ System |
| `topology` | 2 | PostGIS extension tables | ✅ System |
| **TOTAL** | **127+** | **Multi-domain architecture** | **Established** |

---

## 🔧 Core System Components

### 1. Authentication & Identity Management
- **Dual Entity Model:** `Person` (human) ↔ `User` (technical account)
- **JWT Token Handling:** Secure session management with refresh tokens
- **Role-Based Access Control:** Admin, Fleet Manager, Service Provider, User roles
- **Organization Membership:** Users can belong to multiple organizations with different roles

### 2. Asset & Vehicle Management
- **2-Step Creation Process:**
  1. **Draft Phase:** Basic categorization (make, model, year) → Limited capabilities
  2. **Verification Phase:** VIN/registration validation → Full "Active" status with digital twin
- **MDM Deduplication:** Merge only when `make`, `technical_code`, AND `engine_capacity` match
- **Vehicle Catalog:** `vehicle_model_definitions` with `gold_enriched` status tracking

### 3. Financial Engine (Triple Wallet)
- **Local Currency (HUF):** Primary operational wallet
- **EUR Wallet:** Cross-border transactions
- **Token Wallet:** Gamification rewards, loyalty points
- **Audit Trail:** Every transaction logged in `finance.ledger` with balance validation

### 4. Marketplace & Service Discovery
- **Service Profiles:** Geotagged service offerings with specialization tags
- **Provider Network:** Verified service providers with ratings
- **Booking Flow:** Request → Quote → Acceptance → Completion workflow
- **Geofenced Broadcast:** Spatial matching of service requests to qualified providers

### 5. Gamification & Engagement
- **XP System:** Points for vehicle registration, service completion, reviews
- **Badge Hierarchy:** Achievement tiers with visual rewards
- **Leaderboards:** Organization and global rankings
- **Daily Quizzes:** Knowledge reinforcement with token rewards

---

## 🤖 Robot Ecosystem (Automated Workers)

### Vehicle Data Pipeline
| Robot | Purpose | Status | Data Source |
|-------|---------|--------|-------------|
| **R0-GB Discovery** | UK MOT CSV ingestion | ✅ Active | Local CSV file |
| **R1-GB Hunter** | DVLA VES API queries | ✅ Active | DVLA API (UK) |
| **R2-Researcher** | Technical data enrichment | ✅ Active | RDW (NL), Auto-Data.net |
| **R3-Alchemist** | Data validation & gold flagging | ✅ Active | Internal rules |
| **R4-Validator** | VIN audit & consistency checks | ✅ Active | Multiple sources |

### Service & Operational Robots
| Robot | Purpose | Status |
|-------|---------|--------|
| **Service Scout** | OSM-based service discovery | ✅ Active |
| **Service Enricher** | Provider data enhancement | ✅ Active |
| **Service Validator** | Quality assurance checks | ✅ Active |
| **Service Auditor** | Compliance monitoring | ✅ Active |
| **OCR Processor** | Document extraction (receipts, invoices) | ✅ Active |

### Quota Management
- **DVLA API Limit:** 1000 calls/day (configurable via `DVLA_DAILY_LIMIT`)
- **Usage Tracking:** `.quota_dvla.json` with timestamp logging
- **Rate Limit Handling:** Exponential backoff for 429 responses

---

## 🐳 Container Infrastructure

### Service Mesh (Docker Compose V2)
```
sf_api:8000              # FastAPI backend
sf_frontend:3000         # Vue admin dashboard  
sf_public_frontend:3001  # Nuxt public interface
postgres:5432            # PostgreSQL with PostGIS
redis:6379               # Redis cache & queues
minio:9000               # MinIO object storage
pgadmin:5050             # Database administration
roo-helper              # AI/script execution container
+ 20+ supporting services
```

### Network Architecture
- **Internal Network:** `sf_network` for service-to-service communication
- **External Exposure:** Nginx reverse proxy with SSL termination
- **API Gateway:** Unified `/api/v1/*` routing with CORS configuration
- **Health Monitoring:** Container health checks and auto-restart policies

---

## 📊 Data Flow Architecture

### Vehicle Registration Pipeline
```
User Input → Frontend (Vue) → /api/v1/assets/vehicles → AssetService → 
Draft Creation → VIN Validation → Robot Enrichment → Gold Flagging → 
Active Asset → Digital Twin → Marketplace Eligibility
```

### Financial Transaction Flow
```
Action Trigger → Wallet Balance Check → Triple Ledger Update → 
Audit Log Entry → Notification Dispatch → Gamification XP Award
```

### Service Discovery Flow
```
User Request → Geospatial Query → Provider Matching → 
Broadcast → Quote Collection → User Selection → Booking Creation
```

---

## 🔒 Security & Compliance

### Data Protection
- **Schema Isolation:** Financial data in `finance`, identity in `identity`, etc.
- **Encryption at Rest:** Sensitive fields encrypted via PostgreSQL pgcrypto
- **Audit Trails:** All critical operations logged in `audit` schema
- **GDPR Compliance:** Right to erasure implemented via soft deletion

### API Security
- **JWT Authentication:** Bearer tokens with short expiration
- **Rate Limiting:** Per-user and per-IP request throttling
- **Input Validation:** Pydantic models with strict type checking
- **SQL Injection Protection:** Parameterized queries via SQLAlchemy

---

## 📈 System Health Metrics

### Current Status (70% Complete)
- **Database:** 100% synchronized (127+ tables across 19 schemas)
- **Backend API:** 80% implemented (core endpoints functional)
- **Frontend UI:** 60% built (components exist but API wiring incomplete)
- **Robot Fleet:** 100% operational (10+ specialized workers)
- **Integration:** 40% complete (frontend/backend API mismatches present)

### Performance Characteristics
- **API Response Time:** < 200ms for most endpoints
- **Database Queries:** < 50ms average with proper indexing
- **Concurrent Users:** Designed for 1000+ simultaneous sessions
- **Data Volume:** Supports 10M+ vehicle records, 100M+ transactions

---

## 🔗 External Dependencies

### Critical APIs
| Service | Purpose | Rate Limit | Status |
|---------|---------|------------|--------|
| **DVLA VES API** | UK vehicle specifications | 1000/day | ✅ Active |
| **RDW API** | Dutch vehicle data | Unknown | ✅ Active |
| **OpenStreetMap** | Geospatial service data | None | ✅ Active |
| **SendGrid** | Email delivery | 100/day | ✅ Configured |

### Infrastructure Dependencies
- **Docker Hub:** Container images
- **Python Package Index:** Python dependencies
- **NPM Registry:** Frontend dependencies
- **Let's Encrypt:** SSL certificates

---

## 🎯 Architectural Principles

### Mandatory Patterns
1. **Async-First:** All I/O operations must be asynchronous
2. **Domain Separation:** No cross-schema direct queries
3. **2-Step Asset Creation:** Draft → Active workflow enforced
4. **Triple Wallet Consistency:** All financial movements audited
5. **Robot Quota Management:** External API calls tracked and limited

### Strict Prohibitions
1. **No Yellow Text on White Backgrounds** (Accessibility)
2. **No Hardcoded API Keys** (Use config.py + .env only)
3. **No Direct Database Drops** (Alembic migrations only)
4. **No Sync Blocking Calls** in FastAPI endpoints
5. **No Schema Mixing** (Finance data stays in finance schema)

---

**Next:** See [02_Database_vs_API_Status.md](02_Database_vs_API_Status.md) for detailed endpoint mapping and implementation gaps.