2026.03.29 20:00 Gitea_manager javítás előtt
This commit is contained in:
Roo
219
docs/v201/01_System_Overview.md
Normal file
219
docs/v201/01_System_Overview.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user