# 🧠 Roo Context File - Service Finder Master Book 2.0.1
**Generated:** 2026-03-26  
**Auditor:** Projekt Manager Gemini  
**Purpose:** System reality snapshot for Roo AI memory & future development context

---

## 📊 CURRENT SYSTEM REALITY (70+ DB Tables, Multi-Schema)

### 🗄️ Database Schema Overview (19 Schemas, 127+ Tables)
| Schema | Table Count | Status |
|--------|-------------|--------|
| audit | 5 | Active (Audit logs) |
| data | 0 | Not in list (maybe missing) |
| finance | 6 | Active (Triple Wallet, Ledger) |
| fleet | 6 | Active (Fleet management) |
| gamification | 11 | Active (XP, Badges, Leaderboard) |
| identity | 7 | Active (Person/User dual model) |
| marketplace | 12 | Active (Services, Providers) |
| public | 4 | System tables |
| system | 15 | Active (Parameters, Translations) |
| tiger | 34 | PostGIS extension tables |
| topology | 2 | PostGIS extension tables |
| vehicle | 25 | Active (Assets, Definitions, History) |
| **TOTAL** | **127+** | **Established multi-schema architecture** |

### ✅ 100% WORKING COMPONENTS (Verified)
1. **Authentication & Token Handling** - JWT with dual entity (Person/User)
2. **Basic Routing** - FastAPI operational on port 8000
3. **Database Connection Pool** - Async SQLAlchemy 2.0+ with PostgreSQL
4. **Docker Stack** - 30+ containers running (API, Frontend, DB, Redis, MinIO, etc.)
5. **Robot Ecosystem** - 10+ specialized workers active (Discovery, Hunter, Enricher, Validator, Auditor)
6. **Multi-Schema Isolation** - DDD principles enforced (identity, finance, vehicle domains separated)

### 🔄 ESTABLISHED WORKFLOWS
- **Vehicle Creation**: 2-step Draft → Active process (frontend calls `/api/v1/vehicles/register`, backend uses `/api/v1/assets/vehicles`)
- **MDM Deduplication**: Merge only when make, technical_code, and engine_capacity match
- **Triple Wallet Economy**: Local/EUR/Token balances with audit trail
- **Robot Quota Management**: `.quota_dvla.json` tracking for API rate limits

---

## ⚠️ KNOWN GAPS & BROKEN PIPES

### 🔴 CRITICAL (Blocking Production)
1. **API Endpoint Mismatch**  
   - Frontend `AddVehicle.vue` calls `/api/v1/vehicles/register` (404 Not Found)
   - Correct endpoint is `/api/v1/assets/vehicles` (requires authentication)
   - **Impact**: Vehicle creation fails for users

2. **Missing 2-Step Vehicle Creation Backend Logic**  
   - Documented 2-step process (Draft → Active) not fully implemented
   - `AssetService.create_or_claim_vehicle()` handles VIN conflicts but draft logic unclear

3. **Authentication Endpoint 404**  
   - `/api/v1/auth/me` returns 404 (should be `/api/v1/users/me` or similar)
   - **Impact**: Frontend cannot validate user session

### 🟡 HIGH PRIORITY (Functional but Incomplete)
4. **Mocked/Broken Catalog Endpoints**  
   - `/api/v1/catalog/brands` - 404 (likely moved to `/api/v1/vehicles/search/brands`)
   - `/api/v1/vehicles/search/brands` - 404 (needs implementation)

5. **Frontend/Backend API Version Drift**  
   - Frontend uses hardcoded IP `192.168.100.43:8000` instead of env variable
   - Multiple API calls expecting different response formats

6. **Missing Historical Data (occurrence_date)**  
   - Epic requirement: "Historical Data (múltbéli költségek, szervizek) bevezetése"
   - `occurrence_date` field not consistently implemented across cost tables

### 🟢 MEDIUM PRIORITY (Architectural Debt)
7. **Inconsistent Error Handling**  
   - Some endpoints return plain text errors, others JSON
   - No standardized error schema

8. **Missing AnalyticsService (TCO/km)**  
   - Flotta Analytics (Total Cost of Ownership per km) not implemented
   - Required for fleet manager dashboards

9. **Robot-0-GB Discovery CSV Path**  
   - Robot expects `/mnt/nas/app_data/uk_mot_data.csv` but file existence not verified

---

## 🏛️ ARCHITECTURAL RULES (Must Preserve)

### 🚫 STRICT PROHIBITIONS
1. **No Yellow Text on White Backgrounds** - Accessibility violation
2. **Never Hardcode API Keys** - Use `config.py` + `.env` only
3. **No Direct Database Drops** - Use Alembic migrations only
4. **No Sync Blocking Calls** - All I/O must be async in FastAPI endpoints
5. **No Schema Mixing** - Finance data stays in `finance` schema, vehicle in `vehicle`, etc.

### ✅ MANDATORY PATTERNS
6. **Vehicle Creation is 2-Step**  
   - Step 1: Draft (VIN optional, basic info)  
   - Step 2: Active (technical enrichment, digital twin creation)  
   - XP reward only after Step 2 completion

7. **Deduplication Logic**  
   - Merge ONLY when `make`, `technical_code`, AND `engine_capacity` match
   - Generate N/A and UNKNOWN fallback codes for SQL constraint compatibility

8. **Robot Quota Enforcement**  
   - All external API calls must respect `DVLA_DAILY_LIMIT` from `.env`
   - Log usage in `.quota_dvla.json` with timestamp

9. **Triple Wallet Transactions**  
   - Every financial movement must create audit trail in `finance.ledger`
   - Balance checks before deductions

### 🔧 TECHNICAL CONSTRAINTS
10. **Docker Compose V2 Only** - Use `docker compose` (space), not `docker-compose`
11. **Roo-Helper Container for Scripts** - All Python operations via `docker exec roo-helper`
12. **Test Database Isolation** - Unit tests must use `service_finder_test` or SQLite in-memory
13. **Logging Standard** - Use `logging.getLogger(__name__)`, no `print()` in production

---

## 📈 SYSTEM HEALTH ASSESSMENT (60% → 70% Complete)

### ✅ STRENGTHS
- **Robust Database Foundation**: 127+ tables across 19 schemas, well-normalized
- **Active Robot Fleet**: 10+ specialized workers running continuously
- **Containerized Infrastructure**: Full Docker stack with monitoring
- **Domain-Driven Design**: Clear separation of concerns (identity, finance, vehicle, marketplace)

### ⚠️ WEAKNESSES
- **Frontend/Backend Integration**: API mismatches causing 404 errors
- **Documentation/Code Drift**: Master Book 2.0 docs don't match actual endpoints
- **Incomplete User Flows**: Vehicle creation, authentication need fixing
- **Limited Testing**: Unit test coverage unknown, integration tests sparse

### 🎯 IMMEDIATE NEXT STEPS (PHASE 2)
1. **Fix API Endpoint Mismatches** - Align frontend calls with backend routes
2. **Implement 2-Step Vehicle Creation** - Complete draft/active workflow
3. **Add Historical Data Fields** - `occurrence_date` across cost tables
4. **Build AnalyticsService** - TCO/km calculations for fleet managers
5. **Create Integration Test Suite** - Verify end-to-end user journeys

---

## 🔗 KEY DEPENDENCIES & RISKS

### 🔄 INTERNAL DEPENDENCIES
- **PostgreSQL 15+** with PostGIS extension (spatial data)
- **Redis** for caching and session management
- **MinIO** for document/evidence storage
- **Ollama** (local AI) + Gemini/Groq (fallback) for OCR/AI

### 🌐 EXTERNAL DEPENDENCIES
- **DVLA VES API** (UK vehicle data) - Rate limited, requires API key
- **RDW API** (Dutch vehicle data) - Public but rate limited
- **OpenStreetMap** (service location data) - No API key required
- **SendGrid** (email) - API key required

### ⚠️ RISK FACTORS
- **Single Point of Failure**: Shared PostgreSQL instance
- **API Rate Limits**: DVLA (1000/day), RDW (unknown)
- **Data Volume**: UK MOT CSV (~10M records) requires efficient processing
- **Complexity**: 30+ Docker containers increase orchestration complexity

---

## 📝 AUDIT METHODOLOGY
1. **Codebase Analysis**: Read backend endpoints, frontend views/stores
2. **Database Inspection**: Schema enumeration via PostgreSQL queries
3. **API Testing**: Direct endpoint calls from roo-helper container
4. **Documentation Comparison**: Master Book 2.0 vs actual implementation
5. **Rule Extraction**: From `.roo/rules/` and code patterns

---

**NEXT ACTION**: Create Gitea issues for each identified gap, prioritize by criticality, begin implementation with Fast Coder mode.
---

## 🏗️ RULE ARCHITECTURE OPTIMIZATION (2026-03-27)

### Multi-Mode Schema Consolidation
- **Updated `00-global.md`**: Added mandatory directives: Docker Compose V2, color scheme (#1e3a8a), DB verification with `sync_engine.py`, ticket verification with `gitea_manager.py`, mandatory 2-step vehicle flow (Draft → Active).
- **Merged `02-architecture.md` into `architect.md`**: Enhanced architect rules with DDD, schema separation, project directory map, and SQL error handling.
- **Merged `04-debug-protocol.md` into `fast-coder.md`**: Added debug protocol steps and rapid API wiring guidelines (Pydantic validation, frontend integration).
- **Path verification**: Updated all references to use `docker compose exec roo-helper` (consistent with Docker Compose V2).

### Environment Cleanup Plan
Identified redundant test folders and orphaned files for archiving (rename to .old and move to archive):
- `backend/app/test_outside/` → `archive/test_outside_old/`
- `backend/app/tests_internal/` → `archive/tests_internal_old/`
- Various `.bak` and `.old` files scattered across the codebase (to be moved to archive).

### Mode Boundary Clarification
Each mode now has clear boundaries to prevent hallucination overlap:
- **Architect**: Focus on DDD, schema design, system integrity, and Kanban management.
- **Fast Coder**: Focus on surgical coding, API wiring, Pydantic validation, and frontend integration.
- **Auditor/Debugger**: Focus on verification, logging, and systematic debugging.

### Next Steps
- Execute archiving of identified redundant files.
- Validate that all rule paths are correct and functional.
- Ensure each mode's custom instructions reflect the updated rule sets.

---

*This file will be updated after each major system change. Maintain as single source of truth for Roo AI context.*