service-finder/readme.md

# 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
```bash
# 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
```bash
# 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
```bash
# 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](./docs/V02/02_Architecture.md)
- [API Specifications](./docs/V02/07_API_Service.md)
- [Database Schema](./docs/V02/06_Database_MDM.md)
- [Robot Ecosystem](./docs/V02/22_Robot_Ecosystem.md)

### 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*