# MotoVaultPro Architecture Documentation

## Table of Contents
1. [Overview](#overview)
2. [Technology Stack](#technology-stack)
3. [Architecture Patterns](#architecture-patterns)
4. [Project Structure](#project-structure)
5. [Data Layer](#data-layer)
6. [Business Logic Layer](#business-logic-layer)
7. [Controller Layer](#controller-layer)
8. [Frontend Architecture](#frontend-architecture)
9. [Authentication & Security](#authentication--security)
10. [Deployment & Configuration](#deployment--configuration)
11. [API Design](#api-design)
12. [Performance Considerations](#performance-considerations)
13. [Development Guidelines](#development-guidelines)
14. [Future Enhancements](#future-enhancements)

## Overview

MotoVaultPro is a self-hosted, open-source vehicle maintenance and fuel mileage tracking application built with ASP.NET Core 8.0. The application follows a traditional Model-View-Controller (MVC) architecture with modern patterns including dependency injection, repository pattern, and dual-database support.

### Key Features
- Vehicle maintenance tracking and reminders
- Fuel efficiency monitoring and analysis
- Multi-user support with role-based access control
- Dual database support (LiteDB and PostgreSQL)
- RESTful API endpoints
- Progressive Web App (PWA) capabilities
- Internationalization support
- OpenID Connect integration
- File attachment and document management

## Technology Stack

### Core Framework
- **ASP.NET Core 8.0** - Web application framework
- **C# 12** - Programming language
- **Razor Pages** - Server-side rendering engine

### Database Support
- **LiteDB 5.0.17** - Embedded NoSQL database (default)
- **PostgreSQL** - External relational database (via Npgsql 9.0.3)

### Frontend Technologies
- **Bootstrap 5** - UI framework and responsive design
- **jQuery** - DOM manipulation and AJAX
- **Chart.js** - Data visualization
- **SweetAlert2** - Modal dialogs and notifications

### Additional Libraries
- **MailKit 4.11.0** - Email functionality
- **CsvHelper 33.0.1** - CSV import/export
- **System.IdentityModel.Tokens.Jwt 7.3.1** - JWT authentication
- **Bootstrap Extensions** - Date pickers, tag inputs, etc.

## Architecture Patterns

### 1. Model-View-Controller (MVC)
Clean separation of concerns with:
- **Models**: Data representation and business logic
- **Views**: User interface and presentation
- **Controllers**: Request handling and application flow

### 2. Repository Pattern
Data access abstraction through interfaces:
- Interface contracts in `External/Interfaces/`
- Dual implementations for LiteDB and PostgreSQL
- Dependency injection for provider selection

### 3. Dependency Injection
Comprehensive DI container usage:
- Service registration in `Program.cs`
- Constructor injection throughout application
- Singleton lifetime for most services

### 4. Generic Record Pattern
Base class inheritance for consistency:
- `GenericRecord` base class with common properties
- Specialized record types for different data types
- Promotes code reuse and maintainability

### 5. Helper/Service Layer Pattern
Business logic separation:
- Helper classes for specific functionality
- Service classes for complex operations
- Clear separation from controllers

## Project Structure

```
MotoVaultPro/
├── Controllers/           # MVC Controllers
│   ├── Vehicle/          # Vehicle-specific controllers
│   ├── HomeController.cs
│   ├── LoginController.cs
│   └── AdminController.cs
├── Models/               # Data models and ViewModels
│   ├── API/             # API-specific models
│   ├── Shared/          # Common models
│   └── Vehicle/         # Vehicle-related models
├── Views/               # Razor views
│   ├── Shared/          # Common layouts and partials
│   └── Vehicle/         # Vehicle-specific views
├── External/            # Data access layer
│   ├── Interfaces/      # Repository interfaces
│   └── Implementations/ # Database implementations
├── Logic/               # Business logic classes
├── Helper/              # Utility classes
├── Middleware/          # Custom middleware
├── wwwroot/            # Static web assets
└── docs/               # Documentation
```

## Data Layer

### Database Architecture
The application supports dual database backends through a unified repository pattern:

#### LiteDB Implementation
- **File-based storage**: Single database file (`data/cartracker.db`)
- **NoSQL document storage**: Entities stored as JSON documents
- **Embedded database**: No external dependencies
- **Performance**: Excellent for single-user scenarios

#### PostgreSQL Implementation
- **Relational database**: External PostgreSQL server
- **Hybrid schema**: Combines relational structure with JSONB flexibility
- **Scalability**: Supports multi-user scenarios with better performance
- **Advanced features**: Full-text search, complex queries, transactions

### Entity Model
```
Vehicle (Root Entity)
├── ServiceRecord (maintenance and repairs)
├── GasRecord (fuel tracking)
├── CollisionRecord (accident records)
├── UpgradeRecord (modifications)
├── TaxRecord (registration and taxes)
├── SupplyRecord (parts and supplies)
├── PlanRecord (maintenance planning)
├── OdometerRecord (mileage tracking)
├── ReminderRecord (maintenance reminders)
└── Note (general notes)
```

### Data Access Interfaces
Each entity type has a dedicated interface:
- `IVehicleDataAccess` - Vehicle management
- `IServiceRecordDataAccess` - Service records
- `IGasRecordDataAccess` - Fuel tracking
- `IUserRecordDataAccess` - User management
- And more...

## Business Logic Layer

### Logic Classes
- **VehicleLogic**: Core vehicle operations and aggregations
- **UserLogic**: User management and access control
- **LoginLogic**: Authentication and user registration
- **OdometerLogic**: Mileage tracking and validation

### Helper Classes
- **ReminderHelper**: Reminder calculations and urgency
- **ReportHelper**: Data aggregation and reporting
- **StaticHelper**: Common utilities and constants
- **TranslationHelper**: Internationalization support
- **ConfigHelper**: Configuration management

### Business Rules
- **Mileage Progression**: Automatic odometer record management
- **Reminder Urgency**: Complex urgency calculations based on date/mileage
- **Access Control**: Vehicle-level permissions with collaborator system
- **Data Validation**: Input validation and business rule enforcement

## Controller Layer

### Main Controllers
- **HomeController**: Dashboard, settings, and kiosk mode
- **VehicleController**: Vehicle management hub (partial class)
- **LoginController**: Authentication and user management
- **AdminController**: Administrative functions
- **APIController**: RESTful API endpoints

### Vehicle Controller Architecture
The `VehicleController` uses a partial class pattern with specialized controllers:
- **GasController**: Fuel record management
- **ServiceController**: Service record operations
- **ReminderController**: Reminder management
- **ImportController**: CSV import/export
- And more...

### Security and Authorization
- **Authentication Middleware**: Custom authentication handler
- **Role-based Authorization**: Admin, root user, and regular user roles
- **Vehicle-level Permissions**: CollaboratorFilter for fine-grained access
- **API Authentication**: Supports both cookie and Basic Auth

## Frontend Architecture

### View Organization
- **Razor Views**: Server-side rendered with strong typing
- **Partial Views**: Modular components for reusability
- **Layout System**: Single layout with sections for customization
- **Modal-heavy UI**: Extensive use of Bootstrap modals

### JavaScript Architecture
- **jQuery-based**: DOM manipulation and AJAX requests
- **Feature-specific files**: Organized by functionality
- **Global functions**: Accessible throughout the application
- **Event-driven**: Extensive event handling for user interactions

### Styling Approach
- **Bootstrap 5**: Primary CSS framework
- **Custom CSS**: Application-specific styling in `site.css`
- **Responsive Design**: Mobile-first approach with media queries
- **Dark Mode Support**: CSS variables for theme switching

### Progressive Web App (PWA)
- **Web App Manifest**: Proper configuration for app installation
- **Service Worker Ready**: Architecture supports offline functionality
- **Multiple Icons**: Various sizes for different devices
- **Responsive Design**: Optimized for mobile and desktop

## Authentication & Security

### Authentication Modes
- **Cookie-based**: Encrypted session cookies for web interface
- **Basic Authentication**: HTTP Basic Auth for API access
- **OpenID Connect**: External provider integration
- **Token-based**: Registration and password reset tokens

### Authorization Levels
- **Root User**: Full system access (user ID -1)
- **Admin User**: Administrative privileges
- **Regular User**: Standard application access
- **Vehicle Collaborators**: Vehicle-specific permissions

### Security Features
- **Password Hashing**: SHA256 with UTF-8 encoding
- **Data Protection**: ASP.NET Core encryption for cookies
- **PKCE Support**: Enhanced OIDC security
- **File Security**: Authenticated file access and uploads
- **SQL Injection Protection**: Parameterized queries throughout

## Deployment & Configuration

### Database Selection
Configuration-driven database selection:
```csharp
if (!string.IsNullOrWhiteSpace(builder.Configuration["POSTGRES_CONNECTION"]))
{
    // Use PostgreSQL
}
else
{
    // Use LiteDB (default)
}
```

### Configuration Management
- **Environment Variables**: Database connections and external services
- **JSON Configuration**: Application settings and user preferences
- **Feature Flags**: Enable/disable authentication and features
- **Multi-environment**: Development, staging, production configurations

### Docker Support
- **Multi-stage build**: Optimized Docker image creation
- **ASP.NET Core 8.0 runtime**: Lightweight production image
- **Port 8080**: Standard web application port
- **Volume mounting**: Persistent data storage

## API Design

### RESTful Endpoints
- **Conventional routing**: `/api/{controller}/{action}`
- **JSON responses**: Consistent response format
- **HTTP status codes**: Proper error handling
- **Authentication required**: All endpoints require authentication

### API Features
- **Vehicle data**: CRUD operations for all record types
- **User management**: Authentication and authorization
- **File operations**: Upload and download capabilities
- **Reporting**: Data aggregation and analysis endpoints

## Performance Considerations

### Database Performance
- **Connection pooling**: Efficient connection management (PostgreSQL)
- **Lazy loading**: On-demand data retrieval
- **Caching**: Configuration and translation caching
- **Batch operations**: Efficient bulk data operations

### Frontend Performance
- **Partial views**: Reduced page load times
- **AJAX updates**: Dynamic content without full page reloads
- **Responsive images**: Optimized for different screen sizes
- **Minification ready**: Architecture supports asset bundling

## Development Guidelines

### Code Organization
- **Separation of concerns**: Clear layer boundaries
- **Consistent naming**: Descriptive class and method names
- **Interface-based design**: Abstraction for testability
- **Dependency injection**: Loose coupling between components

### Best Practices
- **Error handling**: Comprehensive exception management
- **Logging**: Structured logging throughout application
- **Validation**: Input validation at multiple layers
- **Security**: Security-first approach to all features

### Testing Strategy
- **Unit testing**: Business logic and data access layers
- **Integration testing**: API endpoints and workflows
- **UI testing**: Frontend functionality and user flows
- **Security testing**: Authentication and authorization

## Future Enhancements

### Scalability Improvements
- **Microservices**: Potential service decomposition
- **Caching layer**: Redis or in-memory caching
- **Load balancing**: Multi-instance deployment support
- **Database sharding**: Data partitioning for scale

### Technology Upgrades
- **Modern JavaScript**: ES6+ modules and TypeScript
- **Frontend framework**: React, Vue, or Angular integration
- **Real-time features**: SignalR for live updates
- **API versioning**: Structured API evolution

### Feature Enhancements
- **Mobile applications**: Native iOS and Android apps
- **Advanced reporting**: Business intelligence features
- **Integration APIs**: Third-party service connections
- **Automated backups**: Scheduled data protection

### Security Enhancements
- **Multi-factor authentication**: Enhanced security options
- **OAuth 2.0**: Extended authentication provider support
- **API rate limiting**: Protection against abuse
- **Audit logging**: Comprehensive security tracking

---

**Last Updated**: January 2025  
**Version**: 1.0  
**Maintainer**: MotoVaultPro Development Team