8.8 KiB
8.8 KiB
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:
- Draft Phase: Basic categorization (make, model, year) → Limited capabilities
- Verification Phase: VIN/registration validation → Full "Active" status with digital twin
- MDM Deduplication: Merge only when
make,technical_code, ANDengine_capacitymatch - Vehicle Catalog:
vehicle_model_definitionswithgold_enrichedstatus 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.ledgerwith 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.jsonwith 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_networkfor 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 inidentity, etc. - Encryption at Rest: Sensitive fields encrypted via PostgreSQL pgcrypto
- Audit Trails: All critical operations logged in
auditschema - 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
- Async-First: All I/O operations must be asynchronous
- Domain Separation: No cross-schema direct queries
- 2-Step Asset Creation: Draft → Active workflow enforced
- Triple Wallet Consistency: All financial movements audited
- Robot Quota Management: External API calls tracked and limited
Strict Prohibitions
- No Yellow Text on White Backgrounds (Accessibility)
- No Hardcoded API Keys (Use config.py + .env only)
- No Direct Database Drops (Alembic migrations only)
- No Sync Blocking Calls in FastAPI endpoints
- No Schema Mixing (Finance data stays in finance schema)
Next: See 02_Database_vs_API_Status.md for detailed endpoint mapping and implementation gaps.