diff --git a/readme.md b/readme.md new file mode 100644 index 0000000..7ce9cc4 --- /dev/null +++ b/readme.md @@ -0,0 +1,267 @@ +# 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 +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* \ No newline at end of file