# aliases1538/logist_anti architecture

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

- Interactive diagram: https://gitdiagram.com/aliases1538/logist_anti
- Repository: https://github.com/aliases1538/logist_anti

## Overview

This is a **monolithic Flask web application** that serves:
- **Server-rendered UI** (Jinja templates in `backend/templates/`)
- **Static frontend assets** (Vanilla JS/CSS in `backend/static/`)
- **JSON APIs** consumed by the frontend JS (routes under `backend/routes/`)
- **AI/optimization services** implemented in-process (`backend/services/`)
- **Persistence** via **SQLAlchemy** models (`backend/models.py`) targeting **SQLite** by default (`DATABASE_URL=sqlite:///logistics.db`)
- **External integrations**: **OSRM** for routing, **OpenRouter** for chatbot, plus an **image proxy** for image lookup.

##### Browser (User)
- Loads HTML pages
- Runs `main.js`, `map.js`, `chatbot.js`
##### Flask Application Server (`backend/app.py` with `create_app`)
- Registers routes/blueprints from `backend/routes/*`
- Serves templates + JSON APIs + static files
- Applies JWT auth
##### Database (SQLite by default)
- Defined by `DATABASE_URL`
- Models in `backend/models.py`
##### External Services
- **OSRM Public API** (route calculation)
- **OpenRouter API** (chatbot completions)

##### API/Route layer (Blueprint-like modules)
From `backend/routes/`:
- `auth.py`: login/register, JWT issuance and validation flows
- `admin.py`: admin-only stats/user mgmt endpoints (needs “Admin authorization gate”)
- `vehicles.py`: vehicles CRUD + state changes
- `shipments.py`: shipments CRUD + tracking/status
- `optimization.py`: route computation endpoint(s)
- `chatbot.py`: OpenRouter proxy endpoint(s)
- `image_proxy.py`: image fetching proxy endpoint(s)

##### Service / domain logic layer
From `backend/services/`:
- `ai_optimizer.py`: route/assignment optimization logic (Haversine, Dijkstra noted)
- `ml_model.py`: time/fuel prediction (scikit-learn)
- `traffic_service.py`: traffic/congestion enrichment (even if stubbed, it’s an explicit component)

##### Data access layer
- `config.py`: config/env wiring (SECRET_KEY, DB URL, API keys)

##### Authentication
- Browser → `routes/auth.py` → DB (`models.py`)
- `auth.py` → issues **JWT** → Browser stores token
- Browser → subsequent API calls include `Authorization: Bearer <JWT>`

##### Vehicles / Shipments CRUD
- Browser (JS `main.js`) → `routes/vehicles.py` / `routes/shipments.py` → `models.py` → SQLite
- Responses feed UI tables/forms (templates + JS)

##### Map & Routing
- Browser (JS `map.js` + Leaflet) → `routes/optimization.py`
- `optimization.py` → calls:
- **OSRM API** (for real-road routing)
- `services/ai_optimizer.py` (graph/path logic)
- `services/ml_model.py` (ETA/fuel estimates)
- `services/traffic_service.py` (traffic adjustments)
- Returns route geometry/steps/metrics → Browser renders on map

##### AI Chatbot
- Browser (`chatbot.js`) → `routes/chatbot.py`
- `chatbot.py` → **OpenRouter API** → response → Browser chat UI

##### Image Lookup
- Browser → `routes/image_proxy.py`
- `image_proxy.py` → External Image Search API → Browser displays image

##### Admin-only
- Browser → `routes/admin.py` (JWT + admin check) → DB queries → admin dashboards

##### Architectural patterns/design principles to call out
- **Monolith with layered modularization**:
- Routes (controller-like) → Services (business logic) → Models (persistence)
- **Server-rendered + API hybrid**:
- Jinja templates for page shells, JS fetch for dynamic CRUD/interactive map/chat
- **External API façade/proxy** pattern:
- `chatbot.py` and `image_proxy.py` shield keys/CORS and standardize responses
- **App factory** pattern:
- `create_app()` in `backend/app.py` (important for deploy via WSGI and testing)

- Goal: show *what depends on what*.

- Split Flask app internals into:
- Web UI (Templates/Static)
- API routes module group
- Services module group
- ORM/Models
- Browser loading templates/static from Flask, then calling JSON endpoints.

- `models.py` as a shared dependency
- `optimization.py` → `ai_optimizer.py`, `ml_model.py`, `traffic_service.py`, OSRM
- `chatbot.py` → OpenRouter
- `image_proxy.py` → Image API
- `vehicles.py` / `shipments.py` / `admin.py` / `auth.py` → `models.py` → DB

This matches the repo structure closely and avoids hand-wavy grouping.

##### Deployment/hosting element to include (because README mentions it)
A small deployment annotation:
- “WSGI entry (cPanel / passenger_wsgi.py) → `create_app()`”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% System Context (C4-ish)
    %% =========================
    subgraph "System Context"
        U["Browser (User)"]:::frontend

        subgraph "Monolithic Flask Web Application"
            APP["Flask App Server\n(App Factory: create_app)"]:::backend
        end

        DB[("SQLite Database\n(DATABASE_URL=sqlite:///logistics.db)")]:::database

        OSRM["OSRM Public API"]:::external
        OR["OpenRouter API"]:::external
        IMG["External Image Search API"]:::external
    end

    U -->|"HTTPS:GET HTML (Jinja pages)"| APP
    U -->|"HTTPS:GET static assets (CSS/JS)"| APP
    U -->|"HTTPS JSON APIs (Authorization:Bearer JWT)"| APP

    APP -->|"SQLAlchemy ORM (CRUD)"| DB

    APP -->|"HTTPS:route request/geometry"| OSRM
    APP -->|"HTTPS:chat completions"| OR
    APP -->|"HTTPS:image lookup"| IMG

    %% =========================
    %% Container / Internal Layers (inside Flask app)
    %% =========================
    subgraph "Flask App Internals (Single Deployable Monolith)"
        INIT["Flask Package Init"]:::backend
        CFG["Configuration / Env Wiring\n(SECRET_KEY,DB URL,API keys)"]:::config
        MODELS["ORM + Models\n(SQLAlchemy)"]:::data
        WSGI["WSGI/Deployment Utility\n(verify create_app())"]:::deploy

        subgraph "Presentation Layer"
            TEMPL["Templates (Jinja)"]:::frontend
            STATIC["Static Assets (CSS/JS)"]:::frontend

            BASEHTML["base.html"]:::frontend
            DASHHTML["dashboard.html"]:::frontend
            DASHDIR["dashboard/ (templates)"]:::frontend
            DASHIDX["dashboard/index.html"]:::frontend
            AUTHDIR["auth/ (templates)"]:::frontend
            LOGINHTML["auth/login.html"]:::frontend
            MAPDIR["map/ (templates)"]:::frontend
            MAPVIEW["map/view.html"]:::frontend
            T1["transportlar.html"]:::frontend
            T2["xarita.html"]:::frontend
            T3["yuklar.html"]:::frontend

            STYLE["style.css"]:::frontend
            JSDIR["static/js/"]:::frontend
            MAINJS["main.js\n(UI + fetch CRUD)"]:::frontend
            MAPJS["map.js\n(Leaflet + routing UX)"]:::frontend
            CHATJS["chatbot.js\n(chat widget UX)"]:::frontend
        end

        subgraph "Route / API Layer (backend/routes)"
            ROUTESDIR["Routes Module (Directory)"]:::backend

            R_AUTH["auth.py\n(Login/Register + JWT)"]:::api
            R_ADMIN["admin.py\n(Admin-only endpoints)"]:::api
            R_VEH["vehicles.py\n(Vehicles CRUD)"]:::api
            R_SHIP["shipments.py\n(Shipments CRUD + status)"]:::api
            R_OPT["optimization.py\n(Route computation API)"]:::api
            R_CHAT["chatbot.py\n(OpenRouter proxy façade)"]:::api
            R_IMG["image_proxy.py\n(Image proxy façade)"]:::api
        end

        subgraph "Service / Domain Logic Layer (backend/services)"
            SRVDIR["Services Module (Directory)"]:::backend

            S_OPT["ai_optimizer.py\n(Haversine/Dijkstra, assignment)"]:::service
            S_ML["ml_model.py\n(ETA/Fuel prediction, scikit-learn)"]:::service
            S_TRAF["traffic_service.py\n(Traffic/congestion enrichment)"]:::service
        end
    end

    %% Wiring / dependencies
    INIT -->|"imports/initializes"| APP
    CFG -.->|"env vars + secrets"| APP
    CFG -.->|"DB config"| MODELS

    APP -->|"registers routes"| ROUTESDIR
    APP -->|"serves pages"| TEMPL
    APP -->|"serves static"| STATIC

    ROUTESDIR -->|"controllers call"| MODELS
    MODELS -->|"SQLAlchemy ORM"| DB

    %% =========================
    %% Primary user flows
    %% =========================
    U -->|"HTTPS JSON:auth (login/register)"| R_AUTH
    R_AUTH -->|"ORM:users + credentials"| MODELS
    R_AUTH -->|"issues JWT"| U

    U -->|"HTTPS JSON:vehicles CRUD (Bearer JWT)"| R_VEH
    R_VEH -->|"ORM CRUD"| MODELS

    U -->|"HTTPS JSON:shipments CRUD (Bearer JWT)"| R_SHIP
    R_SHIP -->|"ORM CRUD"| MODELS

    U -->|"HTTPS JSON:admin endpoints (JWT+admin gate)"| R_ADMIN
    R_ADMIN -->|"ORM queries"| MODELS

    U -->|"HTTPS JSON:optimization request"| R_OPT
    R_OPT -->|"calls algorithms"| S_OPT
    R_OPT -->|"calls prediction"| S_ML
    R_OPT -->|"calls traffic enrichment"| S_TRAF
    R_OPT -->|"HTTPS:OSRM route geometry"| OSRM
    R_OPT -->|"JSON:route geometry/steps/metrics"| U

    U -->|"HTTPS JSON:chat messages"| R_CHAT
    R_CHAT -->|"HTTPS:OpenRouter completions"| OR
    R_CHAT -->|"JSON:assistant response"| U

    U -->|"HTTPS:GET image via proxy"| R_IMG
    R_IMG -->|"HTTPS:image lookup"| IMG
    R_IMG -->|"image bytes/URL"| U

    %% Templates/static specifics
    U -->|"GET HTML:page shells"| TEMPL
    U -->|"GET CSS/JS"| STATIC

    STATIC -->|"loads"| STYLE
    STATIC -->|"loads"| JSDIR
    JSDIR -->|"runs"| MAINJS
    JSDIR -->|"runs"| MAPJS
    JSDIR -->|"runs"| CHATJS

    TEMPL -->|"includes"| BASEHTML
    TEMPL -->|"renders"| DASHHTML
    TEMPL -->|"contains"| DASHDIR
    DASHDIR -->|"renders"| DASHIDX
    TEMPL -->|"contains"| AUTHDIR
    AUTHDIR -->|"renders"| LOGINHTML
    TEMPL -->|"contains"| MAPDIR
    MAPDIR -->|"renders"| MAPVIEW
    TEMPL -->|"renders"| T1
    TEMPL -->|"renders"| T2
    TEMPL -->|"renders"| T3

    %% Deployment note
    WSGI -->|"verifies create_app()"| APP

    %% =========================
    %% Click Events (from mapping)
    %% =========================
    click APP "https://github.com/aliases1538/logist_anti/blob/main/backend/app.py"
    click INIT "https://github.com/aliases1538/logist_anti/blob/main/backend/__init__.py"
    click CFG "https://github.com/aliases1538/logist_anti/blob/main/backend/config.py"
    click MODELS "https://github.com/aliases1538/logist_anti/blob/main/backend/models.py"

    click ROUTESDIR "https://github.com/aliases1538/logist_anti/tree/main/backend/routes/"
    click R_AUTH "https://github.com/aliases1538/logist_anti/blob/main/backend/routes/auth.py"
    click R_ADMIN "https://github.com/aliases1538/logist_anti/blob/main/backend/routes/admin.py"
    click R_VEH "https://github.com/aliases1538/logist_anti/blob/main/backend/routes/vehicles.py"
    click R_SHIP "https://github.com/aliases1538/logist_anti/blob/main/backend/routes/shipments.py"
    click R_OPT "https://github.com/aliases1538/logist_anti/blob/main/backend/routes/optimization.py"
    click R_CHAT "https://github.com/aliases1538/logist_anti/blob/main/backend/routes/chatbot.py"
    click R_IMG "https://github.com/aliases1538/logist_anti/blob/main/backend/routes/image_proxy.py"

    click SRVDIR "https://github.com/aliases1538/logist_anti/tree/main/backend/services/"
    click S_OPT "https://github.com/aliases1538/logist_anti/blob/main/backend/services/ai_optimizer.py"
    click S_ML "https://github.com/aliases1538/logist_anti/blob/main/backend/services/ml_model.py"
    click S_TRAF "https://github.com/aliases1538/logist_anti/blob/main/backend/services/traffic_service.py"

    click TEMPL "https://github.com/aliases1538/logist_anti/tree/main/backend/templates/"
    click BASEHTML "https://github.com/aliases1538/logist_anti/blob/main/backend/templates/base.html"
    click DASHHTML "https://github.com/aliases1538/logist_anti/blob/main/backend/templates/dashboard.html"
    click DASHDIR "https://github.com/aliases1538/logist_anti/tree/main/backend/templates/dashboard/"
    click DASHIDX "https://github.com/aliases1538/logist_anti/blob/main/backend/templates/dashboard/index.html"
    click AUTHDIR "https://github.com/aliases1538/logist_anti/tree/main/backend/templates/auth/"
    click LOGINHTML "https://github.com/aliases1538/logist_anti/blob/main/backend/templates/auth/login.html"
    click MAPDIR "https://github.com/aliases1538/logist_anti/tree/main/backend/templates/map/"
    click MAPVIEW "https://github.com/aliases1538/logist_anti/blob/main/backend/templates/map/view.html"
    click T1 "https://github.com/aliases1538/logist_anti/blob/main/backend/templates/transportlar.html"
    click T2 "https://github.com/aliases1538/logist_anti/blob/main/backend/templates/xarita.html"
    click T3 "https://github.com/aliases1538/logist_anti/blob/main/backend/templates/yuklar.html"

    click STATIC "https://github.com/aliases1538/logist_anti/tree/main/backend/static/"
    click STYLE "https://github.com/aliases1538/logist_anti/blob/main/backend/static/css/style.css"
    click JSDIR "https://github.com/aliases1538/logist_anti/tree/main/backend/static/js/"
    click MAINJS "https://github.com/aliases1538/logist_anti/blob/main/backend/static/js/main.js"
    click MAPJS "https://github.com/aliases1538/logist_anti/blob/main/backend/static/js/map.js"
    click CHATJS "https://github.com/aliases1538/logist_anti/blob/main/backend/static/js/chatbot.js"

    click WSGI "https://github.com/aliases1538/logist_anti/blob/main/backend/verify_app.py"

    %% =========================
    %% Styles
    %% =========================
    classDef frontend fill:#D8F5D0,stroke:#2E7D32,stroke-width:1px,color:#0B2E13
    classDef backend fill:#D6E8FF,stroke:#1E5AA8,stroke-width:1px,color:#0B1F3A
    classDef api fill:#BFD7FF,stroke:#1E5AA8,stroke-width:1px,color:#0B1F3A
    classDef service fill:#C9D8FF,stroke:#3949AB,stroke-width:1px,color:#10183A
    classDef data fill:#E3F2FD,stroke:#1565C0,stroke-width:1px,color:#0B1F3A
    classDef database fill:#E0E0E0,stroke:#424242,stroke-width:1px,color:#1A1A1A
    classDef external fill:#FFE0B2,stroke:#EF6C00,stroke-width:1px,color:#4A2A00
    classDef config fill:#FFF9C4,stroke:#F9A825,stroke-width:1px,color:#3A2A00
    classDef deploy fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px,color:#2A083A
```
