motovaultpro/docs/architecture.md

MotoVaultPro Architecture Documentation

Table of Contents

1. Overview
2. Technology Stack
3. Architecture Patterns
4. Project Structure
5. Data Layer
6. Business Logic Layer
7. Controller Layer
8. Frontend Architecture
9. Authentication & Security
10. Deployment & Configuration
11. API Design
12. Performance Considerations
13. Development Guidelines
14. 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:

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