# somanshi282/fleetflow architecture

> Architecture diagram of the GitHub repository somanshi282/fleetflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/somanshi282/fleetflow
- Repository: https://github.com/somanshi282/fleetflow

## Overview

##### What this project is (type + purpose) from the tree/README
This is a small **full-stack web application** with:
- A **Node.js/Express backend** (typical structure: `server.js`, `src/app.js`, `controllers/`, `routers/`, `middleware/`, `models/`, `config/`)
- A **static frontend** served as HTML/CSS/vanilla JS pages under `frontend/public/` (multiple screens: login/register, analytics, performance, maintenance, trip dispatcher/expense, vehicle registry)

The README doesn’t describe features/stack, but the file tree strongly indicates:
- **Backend provides authentication APIs** (see `authController.js`, `authRoutes.js`, `authMiddleware.js`, `models/user.js`)
- **Database-backed user storage** (see `config/database.sql`, `config/db.js`)
- **Frontend is not a framework SPA**; it’s multiple standalone HTML pages with JS files that call backend endpoints.

##### How to analyze the structure into diagrammable components
Use the file tree as the authoritative source of components:

##### Backend (Node/Express)
- **Entry / bootstrap**
- `backend/server.js` (likely starts HTTP server, listens on port)
- `backend/src/app.js` (likely Express app setup: middleware, routes, etc.)
- **Routing layer**
- `backend/routers/authRoutes.js` (defines `/auth/...` endpoints)
- **Controller layer**
- `backend/controllers/authController.js` (request handlers: login/register/etc.)
- **Middleware**
- `backend/middleware/authMiddleware.js` (JWT/session validation; protects routes)
- **Model / data access**
- `backend/models/user.js` (user schema/queries)
- **Configuration**
- `backend/config/db.js` (DB connection pool/client)
- `backend/config/database.sql` (DDL: user table, etc.)
- `backend/.env.example` (environment variables: DB creds, JWT secret, port)

##### Frontend (static assets)
- **HTML pages (views)**
- `index.html`, `login.html`, `register.html`
- Domain pages: `analytics.html`, `performance.html`, `maintenance.html`, `trip-dispatcher.html`, `trip-expense.html`, `vehicle-registry.html`
- **Client-side logic**
- `public/app.js`, `ui-logic.js`, plus page-specific JS: `analytics.js`, `performance.js`, `maintenance.js`, `trip-expense.js`, `vehicle.js`
- **Styling**
- `style.css`, `style2.css`, `animations.css`

Optionally add:

##### JSON response returned

These sequences let you be “detailed” even when domain endpoints beyond auth aren’t shown in the tree.

- router imports controller
- controller imports model
- model imports db client
- Auth is shown as:
- endpoint(s) in routes
- logic in controller
- enforcement in middleware
- Database is explicitly shown and connected via `config/db.js`.
- Frontend pages are shown as modules with JS files attached.

- C1 (Context): user + browser + system + DB
- C2 (Containers): frontend static server (or “static files”), backend API server, DB
- C3 (Components): Express internals mapped to your directories

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% C1/C2: System Context + Containers (vertical)
    %% =========================
    U["User (Driver/Admin/Dispatcher)"]:::actor
    B["Web Browser"]:::client

    subgraph "Presentation Layer (Static Multi-Page Frontend)"
        FE_ROOT["Static Frontend Assets"]:::frontend

        subgraph "Pages (HTML)"
            FE_INDEX["Home / Dashboard (index.html)"]:::frontend
            subgraph "Auth Pages"
                FE_LOGIN["Login (login.html)"]:::frontend
                FE_REGISTER["Register (register.html)"]:::frontend
            end
            subgraph "Reporting Pages"
                FE_ANALYTICS["Analytics (analytics.html)"]:::frontend
                FE_PERFORMANCE["Performance (performance.html)"]:::frontend
            end
            subgraph "Operations Pages"
                FE_TRIP_DISPATCH["Trip Dispatcher (trip-dispatcher.html)"]:::frontend
                FE_TRIP_EXPENSE["Trip Expense (trip-expense.html)"]:::frontend
                FE_VEHICLE_REG["Vehicle Registry (vehicle-registry.html)"]:::frontend
            end
            FE_MAINT["Maintenance (maintenance.html)"]:::frontend
        end

        subgraph "Client-side JS"
            FE_APPJS["Shared Logic (app.js)"]:::frontend
            FE_UI["UI Helpers (ui-logic.js)"]:::frontend
            FE_AJS["analytics.js"]:::frontend
            FE_PJS["performance.js"]:::frontend
            FE_MJS["maintenance.js"]:::frontend
            FE_TEJS["trip-expense.js"]:::frontend
            FE_VJS["vehicle.js"]:::frontend
        end

        subgraph "Styles"
            FE_STYLE1["style.css"]:::asset
            FE_STYLE2["style2.css"]:::asset
            FE_ANIM["animations.css"]:::asset
        end
    end

    subgraph "Backend Layer (Node.js + Express API Server)"
        BE_API["Express API Server"]:::backend

        subgraph "Runtime Entry & App Setup"
            BE_SERVER["HTTP Server Bootstrap (server.js)"]:::backend
            BE_APP["Express App Setup (src/app.js)"]:::backend
        end

        subgraph "Auth Module (Express Internals)"
            BE_AUTH_ROUTER["Auth Router (authRoutes.js)"]:::backend
            BE_AUTH_MW["Auth Middleware (authMiddleware.js)"]:::backend
            BE_AUTH_CTRL["Auth Controller (authController.js)"]:::backend
            BE_USER_MODEL["User Model / Data Access (user.js)"]:::backend
        end

        subgraph "Config & Provisioning"
            BE_ENV["Environment Template (.env.example)"]:::config
            BE_DBCLIENT["DB Client / Pool (config/db.js)"]:::backend
            BE_DDL["Schema Source (config/database.sql)"]:::config
        end
    end

    DB[("SQL Database")]:::database

    %% -------------------------
    %% Context flows
    %% -------------------------
    U -->|"uses"| B
    B -->|"HTTPGETstaticpages/assets"| FE_ROOT

    FE_ROOT -->|"loads"| FE_INDEX
    FE_ROOT -->|"loads"| FE_LOGIN
    FE_ROOT -->|"loads"| FE_REGISTER
    FE_ROOT -->|"loads"| FE_ANALYTICS
    FE_ROOT -->|"loads"| FE_PERFORMANCE
    FE_ROOT -->|"loads"| FE_TRIP_DISPATCH
    FE_ROOT -->|"loads"| FE_TRIP_EXPENSE
    FE_ROOT -->|"loads"| FE_VEHICLE_REG
    FE_ROOT -->|"loads"| FE_MAINT

    FE_INDEX -->|"loadsJS"| FE_APPJS
    FE_INDEX -->|"loadsJS"| FE_UI

    FE_LOGIN -->|"fetch()JSONPOST/auth/login"| BE_API
    FE_REGISTER -->|"fetch()JSONPOST/auth/register"| BE_API

    FE_ANALYTICS -->|"callsAPI(TBD)"| BE_API
    FE_PERFORMANCE -->|"callsAPI(TBD)"| BE_API
    FE_TRIP_DISPATCH -->|"callsAPI(TBD)"| BE_API
    FE_TRIP_EXPENSE -->|"callsAPI(TBD)"| BE_API
    FE_VEHICLE_REG -->|"callsAPI(TBD)"| BE_API
    FE_MAINT -->|"callsAPI(TBD)"| BE_API

    BE_API -->|"JSONresponses(token/user/errors)"| B
    B -->|"tokenstoredclient-side(TBD)"| B

    %% -------------------------
    %% Backend internal wiring (C3)
    %% -------------------------
    BE_SERVER -->|"creates&listenswith"| BE_APP
    BE_APP -->|"registersrouteModule"| BE_AUTH_ROUTER

    BE_AUTH_ROUTER -->|"POST/auth/register|POST/auth/login"| BE_AUTH_CTRL
    BE_APP -->|"guardsprotectedrouteswith"| BE_AUTH_MW
    BE_AUTH_MW -->|"JWTvalidation&attachreq.user"| BE_AUTH_CTRL

    BE_AUTH_CTRL -->|"CRUDusers"| BE_USER_MODEL
    BE_USER_MODEL -->|"SQLvia"| BE_DBCLIENT
    BE_DBCLIENT -->|"SQLqueries(SELECT/INSERT)"| DB

    BE_ENV -.->|"providesDBcreds/JWTsecret/port"| BE_APP
    BE_DDL -.->|"provisionsschema"| DB

    %% =========================
    %% C4-like Sequences (as subgraphs, vertical)
    %% =========================
    subgraph "Sequence: Register (POST /auth/register)"
        S1U["User"]:::actor
        S1B["Browser"]:::client
        S1P["register.html"]:::frontend
        S1R["authRoutes.js"]:::backend
        S1C["authController.register"]:::backend
        S1M["user.js"]:::backend
        S1D["SQL DB"]:::database

        S1U -->|"fillsform"| S1B
        S1B -->|"submits"| S1P
        S1P -->|"fetch()JSONPOST/auth/register"| S1R
        S1R -->|"routesTo"| S1C
        S1C -->|"createUser()"| S1M
        S1M -->|"INSERTusers"| S1D
        S1C -->|"returnstoken+user"| S1B
    end

    subgraph "Sequence: Login (POST /auth/login)"
        S2U["User"]:::actor
        S2B["Browser"]:::client
        S2P["login.html"]:::frontend
        S2R["authRoutes.js"]:::backend
        S2C["authController.login"]:::backend
        S2M["user.js"]:::backend
        S2D["SQL DB"]:::database

        S2U -->|"fillsform"| S2B
        S2B -->|"submits"| S2P
        S2P -->|"fetch()JSONPOST/auth/login"| S2R
        S2R -->|"routesTo"| S2C
        S2C -->|"findUser+verifyPassword"| S2M
        S2M -->|"SELECTusers"| S2D
        S2C -->|"returnstoken"| S2B
    end

    subgraph "Sequence: Authenticated Request (generic protected endpoint)"
        S3B["Browser"]:::client
        S3JS["Frontend JS (fetch)"]:::frontend
        S3MW["authMiddleware.js"]:::backend
        S3CTRL["Controller (protected)"]:::backend
        S3DB["SQL DB"]:::database

        S3B -->|"includesAuthorization:Bearer<TOKEN>"| S3JS
        S3JS -->|"HTTPGET/POSTprotected(TBD)"| S3MW
        S3MW -->|"validatesJWT"| S3CTRL
        S3CTRL -->|"optionalSQLquery"| S3DB
        S3CTRL -->|"JSONresponse"| S3B
    end

    %% =========================
    %% Click Events (from mapping)
    %% =========================
    click BE_SERVER "https://github.com/somanshi282/fleetflow/blob/main/backend/server.js"
    click BE_APP "https://github.com/somanshi282/fleetflow/blob/main/backend/src/app.js"
    click BE_AUTH_ROUTER "https://github.com/somanshi282/fleetflow/blob/main/backend/routers/authRoutes.js"
    click BE_AUTH_CTRL "https://github.com/somanshi282/fleetflow/blob/main/backend/controllers/authController.js"
    click BE_AUTH_MW "https://github.com/somanshi282/fleetflow/blob/main/backend/middleware/authMiddleware.js"
    click BE_USER_MODEL "https://github.com/somanshi282/fleetflow/blob/main/backend/models/user.js"
    click BE_DBCLIENT "https://github.com/somanshi282/fleetflow/blob/main/backend/config/db.js"
    click BE_DDL "https://github.com/somanshi282/fleetflow/blob/main/backend/config/database.sql"
    click BE_ENV "https://github.com/somanshi282/fleetflow/blob/main/backend/.env.example"

    click FE_ROOT "https://github.com/somanshi282/fleetflow/tree/main/frontend/public/"
    click FE_INDEX "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/index.html"
    click FE_LOGIN "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/login.html"
    click FE_REGISTER "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/register.html"
    click FE_ANALYTICS "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/analytics.html"
    click FE_PERFORMANCE "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/performance.html"
    click FE_TRIP_DISPATCH "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/trip-dispatcher.html"
    click FE_TRIP_EXPENSE "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/trip-expense.html"
    click FE_VEHICLE_REG "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/vehicle-registry.html"
    click FE_MAINT "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/maintenance.html"

    click FE_APPJS "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/app.js"
    click FE_UI "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/ui-logic.js"
    click FE_AJS "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/analytics.js"
    click FE_PJS "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/performance.js"
    click FE_MJS "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/maintenance.js"
    click FE_TEJS "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/trip-expense.js"
    click FE_VJS "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/vehicle.js"

    click FE_STYLE1 "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/style.css"
    click FE_STYLE2 "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/style2.css"
    click FE_ANIM "https://github.com/somanshi282/fleetflow/blob/main/frontend/public/animations.css"

    %% =========================
    %% Styles (colors)
    %% =========================
    classDef actor fill:#f3f4f6,stroke:#6b7280,color:#111827,stroke-width:1px
    classDef client fill:#dbeafe,stroke:#2563eb,color:#0f172a,stroke-width:1px
    classDef frontend fill:#bfdbfe,stroke:#1d4ed8,color:#0b1220,stroke-width:1px
    classDef asset fill:#e0f2fe,stroke:#0284c7,color:#0b1220,stroke-width:1px
    classDef backend fill:#bbf7d0,stroke:#16a34a,color:#052e12,stroke-width:1px
    classDef database fill:#fed7aa,stroke:#c2410c,color:#2a0a00,stroke-width:1px
    classDef config fill:#e5e7eb,stroke:#6b7280,color:#111827,stroke-width:1px
```
