219 lines
8.8 KiB
Markdown
219 lines
8.8 KiB
Markdown
# 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. |