Service Finder Platform

📋 Overview

Service Finder is a comprehensive vehicle service and fleet management platform that connects vehicle owners with service providers across Europe. The system combines real-time service discovery, historical data analytics, and automated workflow management.

🚀 Features

Core Capabilities

• Vehicle Master Data Management - Centralized catalog with European vehicle specifications
• Service Discovery Engine - Automated search for service providers across multiple countries
• Fleet Management - Complete TCO (Total Cost of Ownership) tracking and analytics
• Historical Data Integration - Past service records and expense tracking with occurrence dates
• Multi-language Support - Hungarian and English interfaces

Technical Features

• Hybrid AI Gateway - Local Ollama (14B Qwen) for text processing with Gemini/Groq fallback
• Dual Entity Model - Separate Person (human) and User (technical account) entities
• Triple Wallet Economy - Integrated financial system for transactions
• MDM Deduplication - Smart merging based on make, technical_code, and cylinder capacity
• Real-time OCR Processing - Automated document analysis for service receipts

🏗️ Architecture

Tech Stack

• Backend: FastAPI v2 (async), SQLAlchemy (Async), PostgreSQL with PostGIS
• Frontend: Vue.js 3 with Vite, Tailwind CSS
• Database: PostgreSQL 15+ with spatial extensions
• Message Queue: Redis for background job processing
• Containerization: Docker Compose V2
• Reverse Proxy: Nginx Proxy Manager

Database Schema

The system uses a sophisticated schema with:

• Identity & Auth: Dual entity model with JWT-based authentication
• Vehicle Catalog: European vehicle definitions with RDW/DVLA integration
• Service Marketplace: Provider listings with geospatial search
• Fleet Operations: Asset tracking, maintenance scheduling, cost analysis
• Gamification: User engagement system with badges and rewards

🤖 Robot Ecosystem

Discovery Robots

• Robot-0-GB: GB Discovery Engine - Processes UK MOT CSV data
• Robot-1-GB: GB Hunter - Queries DVLA VES API for technical specifications
• Service Robots: Automated service provider discovery and validation

Processing Robots

• OCR Processor: Extracts data from service receipts and documents
• Service Auditor: Validates service provider information
• Research Bots: Enrich vehicle and service data from external sources

📊 Data Sources

Vehicle Data

• RDW API (Netherlands) - Official Dutch vehicle registry
• DVLA VES API (UK) - British vehicle technical specifications
• OpenStreetMap - Service provider locations and details
• Google Places API - Business information and reviews

Service Data

• Historical Service Records - Imported from user uploads
• Provider Directories - Aggregated from multiple European sources
• Real-time Availability - Dynamic scheduling integration

🔧 Installation & Setup

Prerequisites

• Docker and Docker Compose
• PostgreSQL 15+
• Python 3.11+
• Redis 7+

Quick Start

# Clone the repository
git clone <repository-url>
cd service_finder

# Copy environment configuration
cp .env.example .env
# Edit .env with your settings

# Start the services
docker-compose up -d

# Run database migrations
docker-compose exec api alembic upgrade head

# Seed initial data
docker-compose exec api python -m app.scripts.seed_v1_9_system

Development Setup

# Backend development
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run tests
pytest app/tests_internal/

# Start development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

📁 Project Structure

service_finder/
├── backend/                 # FastAPI application
│   ├── app/
│   │   ├── api/            # API endpoints
│   │   ├── models/         # SQLAlchemy models
│   │   ├── schemas/        # Pydantic schemas
│   │   ├── services/       # Business logic
│   │   ├── workers/        # Background robots
│   │   └── tests_internal/ # Test suite
│   ├── migrations/         # Alembic migrations
│   └── requirements.txt
├── frontend/               # Vue.js application
│   ├── src/
│   │   ├── components/     # Vue components
│   │   ├── views/         # Page views
│   │   └── router/        # Vue Router
│   └── package.json
├── docker-compose.yml      # Service definitions
└── readme.md              # This file

🔐 Authentication & Authorization

User Roles

• Super Admin: Full system access
• Organization Admin: Manages fleet and users within organization
• Fleet Manager: Views and manages vehicle assets
• Service Provider: Manages service listings and appointments
• Vehicle Owner: Basic user with personal vehicle management

Security Features

• JWT token-based authentication
• Role-based access control (RBAC)
• API rate limiting
• Input validation and sanitization
• SQL injection prevention
• CORS configuration

📈 API Documentation

Available Endpoints

• /api/v1/auth/ - Authentication and user management
• /api/v1/vehicles/ - Vehicle catalog and operations
• /api/v1/services/ - Service discovery and booking
• /api/v1/fleet/ - Fleet management endpoints
• /api/v1/admin/ - Administrative functions
• /api/v1/analytics/ - Data analysis and reporting

API Versioning

The API uses URL versioning (/api/v1/) with semantic versioning for breaking changes.

🧪 Testing

Test Types

• Unit Tests: Individual component testing
• Integration Tests: API endpoint testing
• Database Tests: Data persistence validation
• Robot Tests: Background job verification

Running Tests

# Run all tests
docker-compose exec api pytest

# Run specific test category
docker-compose exec api pytest app/tests_internal/ -v

# Generate coverage report
docker-compose exec api pytest --cov=app --cov-report=html

📊 Monitoring & Logging

Logging Strategy

• Structured JSON logging for all services
• Centralized log aggregation
• Error tracking and alerting
• Performance metrics collection

Health Checks

• /health: Basic service health
• /health/db: Database connectivity
• /health/redis: Redis connection status
• /health/workers: Background worker status

🔄 Deployment

Production Considerations

• Use environment-specific configuration
• Enable HTTPS with valid certificates
• Configure proper backup strategies
• Set up monitoring and alerting
• Implement CI/CD pipeline

Scaling

• Horizontal scaling of API instances
• Database connection pooling
• Redis clustering for session management
• CDN for static assets

🤝 Contributing

Development Workflow

1. Check the Kanban board for active tasks
2. Create a feature branch from main
3. Implement changes with tests
4. Submit pull request for review
5. Move Kanban card to "Done" after merge

Code Standards

• Follow PEP 8 for Python code
• Use TypeScript for frontend components
• Write comprehensive docstrings
• Include unit tests for new features
• Update documentation as needed

📚 Documentation

Additional Resources

• Architecture Documentation
• API Specifications
• Database Schema
• Robot Ecosystem

Wiki

Comprehensive documentation is maintained in the project Wiki with:

• Technical specifications
• User guides
• API references
• Deployment guides

📞 Support

Issue Reporting

• Use the issue tracker for bugs and feature requests
• Include detailed reproduction steps
• Provide relevant logs and screenshots

Community

• Join the development discussions
• Share feedback and suggestions
• Contribute to documentation

📄 License

This project is proprietary software. All rights reserved.

🏆 Acknowledgments

• European vehicle data providers (RDW, DVLA)
• OpenStreetMap community
• FastAPI and Vue.js communities
• All contributors and testers

---

Last Updated: March 2026