# hargata/lubelog architecture

> Architecture diagram of the GitHub repository hargata/lubelog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hargata/lubelog
- Repository: https://github.com/hargata/lubelog

## Overview

##### Project Type and Purpose
- This is a full-stack, web-based, self-hosted vehicle maintenance and fuel mileage tracker built with ASP.NET Core MVC.
- It serves HTML/JS/CSS to a browser, processes user actions in Controllers, applies domain logic, and persists data to a database (LiteDB or PostgreSQL).
- Key use-cases: user authentication (including OpenID Connect), CRUD over vehicle records (gas, service, reminders, etc.), reporting (charts), file uploads, import/export, and email notifications.

##### Architectural Layers and Components
a. Presentation Layer (Frontend)
- Browser clients load HTML views (Razor .cshtml) served by the ASP.NET app.
- Static assets under wwwroot: CSS, JS (jQuery, Bootstrap, Chart.js, Drawdown, SweetAlert2, Masonry, date-picker).
- Views are organized per area (Home, Login, Vehicle, Admin, API, Migration, Shared).
b. Web Application Layer (ASP.NET Core MVC)
- Program.cs + Startup configuration -> Middleware pipeline (middleware/Authen.cs for authentication).
- Controllers folder: one controller per function/area, delegating to Logic.
c. Business Logic Layer
- Logic folder: classes encapsulating domain rules and orchestration (e.g., VehicleLogic, UserLogic, OdometerLogic, LoginLogic).
- MapProfile: AutoMapper profiles for mapping between Models and database entities.
d. Data Access Layer (Repository Pattern)
- External/Interfaces: repositories interfaces (e.g., IVehicleDataAccess, I**RecordDataAccess).
- External/Implementations:
– LiteDB implementation classes (persist to embedded LiteDB).
– Postgres implementation classes (persist via Npgsql).
- Dependency Injection resolves interfaces to the chosen implementation at runtime.
e. Domain Models and View Models
- Models folder: domain entities, input/edit/view models for UI, config models (MailConfig, ServerConfig), API models, OperationResponse.
f. Infrastructure and Helpers
- Helper folder: utility classes for configuration, file handling, emailing (MailKit), reporting, translations, etc.
- Filter folder: MVC action filters (e.g., CollaboratorFilter).
g. External Services / Integrations
- SMTP server via MailKit for email reminders.
- Optional external OpenID Connect provider (Models/OIDC).
- Docker containers (Postgres, Traefik) or Windows standalone.
- Kubernetes Helm chart support.
h. Database
- Two supported backends: embedded LiteDB (file storage) or PostgreSQL (server).
- init.sql for schema initialization when using Postgres.
- Connection config in appsettings.json / appsettings.Development.json.

- Inside, show the Middleware pipeline.
- Controllers → Business Logic → Data Access interfaces → Data Access implementations.
- Static file server serving wwwroot assets.
3. Below Business Logic, show MapProfile (mapping) and Helper utilities.
- LiteDB file (local .db file)
- PostgreSQL server (container or external host)
5. Above/in parallel to DB, show External Services:
- SMTP Mail server
- (Optional) OpenID Connect provider (for external authentication)
6. At the bottom, include Infrastructure:
- Docker / Traefik reverse proxy
- Kubernetes (Helm)
- CI/CD workflow (.github/workflows build-and-push-image.yml)

##### Relationships and Data Flow
- Browser → Traefik (optional) → ASP.NET Middleware → Controllers.
- Controllers call Logic classes.
- Logic uses repository interfaces to fetch/persist data.
- Repository implementations write to LiteDB file or PostgreSQL.
- Logic may invoke Helper.MailHelper → SMTP.
- Logic may invoke MapProfile (AutoMapper) → Models / ViewModels.
- Controllers return Razor views or JSON (APIController).

##### Key Architectural Patterns
- MVC: clear separation of Models, Views, Controllers.
- Repository Pattern & Dependency Injection: decouple business logic from data storage.
- Middleware pipeline for cross-cutting concerns (authentication, error handling).
- AutoMapper for model mapping.
- Modular areas (Admin, API, Migration, Vehicle sub-areas).

##### Technologies and Frameworks
- ASP.NET Core MVC, Razor.
- LiteDB & Npgsql (PostgreSQL).
- Bootstrap (UI), Bootstrap-DatePicker, SweetAlert2, Chart.js, Drawdown, Masonry.
- MailKit (SMTP).
- Docker, Traefik, GitHub Actions, Helm (Kubernetes).
- CSV import via CsvHelper.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        BrowserClient["Browser Client"]:::presentation
        Views["Razor Views"]:::presentation
        StaticAssets["Static Assets (CSS/JS)"]:::presentation
    end

    %% Web Application Layer
    subgraph "Web Application (ASP.NET Core MVC)"
        direction TB
        Traefik["Traefik / Reverse Proxy"]:::infrastructure
        Program["Program.cs"]:::application
        AuthMiddleware["Authentication Middleware"]:::application
        MiddlewarePipeline["Middleware Pipeline"]:::application
        Controllers["Controllers"]:::application
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        Logic["Logic Classes"]:::application
        MapProfile["AutoMapper Profiles"]:::application
        Helpers["Utility Helpers"]:::application
        Filters["MVC Action Filters"]:::application
        DomainModels["Domain Models & ViewModels"]:::application
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        direction TB
        Interfaces["Data Access Interfaces"]:::dataaccess
        LiteDBImpl["LiteDB Implementations"]:::dataaccess
        PostgresImpl["PostgreSQL Implementations"]:::dataaccess
    end

    %% External Services & Storage
    subgraph "Storage & External Services"
        direction TB
        LiteDBFile["LiteDB File"]:::storage
        PostgresDB["PostgreSQL DB"]:::storage
        SMTP["SMTP Mail Server"]:::external
        OIDC["OpenID Connect Provider"]:::external
    end

    %% Infrastructure & DevOps
    subgraph "Infrastructure & DevOps"
        direction TB
        DockerCompose["Docker Setup"]:::infrastructure
        KubernetesHelm["Kubernetes (Helm)"]:::infrastructure
        CI_CD["GitHub Actions CI/CD"]:::infrastructure
        ConfigFiles["Configuration Files"]:::application
        InitSQL["init.sql"]:::storage
        ProjectEntry["Project Entry (.csproj/.sln)"]:::application
    end

    %% Connections
    BrowserClient -->|"HTTP Request"| Traefik
    Traefik -->|routes to| MiddlewarePipeline
    MiddlewarePipeline -->|auth| AuthMiddleware
    MiddlewarePipeline -->|invoke| Controllers
    Controllers -->|call| Logic
    Logic -->|map via| MapProfile
    Logic -->|use| Helpers
    Logic -->|filter| Filters
    Logic -->|use models| DomainModels
    Logic -->|persist| Interfaces
    Interfaces -->|implements| LiteDBImpl
    Interfaces -->|implements| PostgresImpl
    LiteDBImpl -->|writes| LiteDBFile
    PostgresImpl -->|writes| PostgresDB
    Logic -->|send email| SMTP
    Controllers -->|external login| OIDC

    %% Infrastructure links
    ProjectEntry -->|defines app| Program
    ConfigFiles -->|loaded by| Program
    DockerCompose -->|deploys| Traefik
    DockerCompose -->|deploys| PostgresDB
    KubernetesHelm -->|manages| DockerCompose
    CI_CD -->|build & push| DockerCompose
    PostgresDB -->|schema init| InitSQL

    %% Click Events
    click Views "https://github.com/hargata/lubelog/tree/main/Views/"
    click StaticAssets "https://github.com/hargata/lubelog/tree/main/wwwroot/"
    click Program "https://github.com/hargata/lubelog/blob/main/Program.cs"
    click AuthMiddleware "https://github.com/hargata/lubelog/blob/main/Middleware/Authen.cs"
    click Controllers "https://github.com/hargata/lubelog/tree/main/Controllers/"
    click Logic "https://github.com/hargata/lubelog/tree/main/Logic/"
    click MapProfile "https://github.com/hargata/lubelog/tree/main/MapProfile/"
    click Interfaces "https://github.com/hargata/lubelog/tree/main/External/Interfaces/"
    click LiteDBImpl "https://github.com/hargata/lubelog/tree/main/External/Implementations/Litedb/"
    click PostgresImpl "https://github.com/hargata/lubelog/tree/main/External/Implementations/Postgres/"
    click DomainModels "https://github.com/hargata/lubelog/tree/main/Models/"
    click Helpers "https://github.com/hargata/lubelog/tree/main/Helper/"
    click Filters "https://github.com/hargata/lubelog/tree/main/Filter/"
    click ConfigFiles "https://github.com/hargata/lubelog/blob/main/appsettings.json"
    click DockerCompose "https://github.com/hargata/lubelog/blob/main/docker-compose.yml"
    click CI_CD "https://github.com/hargata/lubelog/blob/main/.github/workflows/build-and-push-image.yml"
    click InitSQL "https://github.com/hargata/lubelog/blob/main/init.sql"
    click ProjectEntry "https://github.com/hargata/lubelog/blob/main/CarCareTracker.csproj"

    %% Styles
    classDef presentation fill:#cce5ff,stroke:#004085,color:#004085;
    classDef application fill:#d4edda,stroke:#155724,color:#155724;
    classDef dataaccess fill:#ffe5b4,stroke:#cc8400,color:#cc8400;
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef infrastructure fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
```
