# muhammadshababb/ai-retail architecture

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

- Interactive diagram: https://gitdiagram.com/muhammadshababb/ai-retail
- Repository: https://github.com/muhammadshababb/ai-retail

## Overview

1. This repository is a server-rendered Flask-style application organized around a single `app/` package, with `run.py` as the entrypoint. The architecture is layered into route handlers, service modules, data models, and HTML templates/static assets.

2. The main user-facing flows are exposed through three route groups: `auth.py` for login/registration, `dashboard.py` for the main analytics experience, and `dataset.py` for data ingestion and schema-related operations. These routes are the HTTP boundary of the system.

3. The core business logic lives in `app/services/`, which is split by responsibility: `etl_service.py` handles dataset ingestion and transformation, `analytics_service.py` computes KPI-style analytics, `ml_service.py` produces demand forecasts, and `insight_service.py` likely synthesizes higher-level business insights from the analytics/ML outputs. This separation keeps the routes thin and the computation reusable.

4. `app/models.py` defines the persistence layer and acts as the shared contract between web routes and service logic. The README’s emphasis on dynamic schema inference suggests datasets are stored in a database and mapped through models or metadata rather than being hardcoded to one retail schema.

5. The data flow starts with file upload or dataset submission, moves through ETL, and then feeds the analytics and forecasting services. The README explicitly mentions CSV/Excel ingestion and automatic schema inference, so the ETL layer is a key boundary between raw user data and normalized application data.

6. The demand intelligence pipeline appears to culminate in forecasting, with the README specifying Holt-Winters Exponential Smoothing for 90-day demand prediction. That makes `ml_service.py` the predictive subsystem, likely consuming historical sales or category-level series produced by ETL.

7. The dashboard layer is presentation-focused: templates like `dashboard.html`, `upload.html`, `schema.html`, `settings.html`, and `about.html` are rendered by the route handlers, with `base.html` and `sidebar.html` providing shared layout structure. This is a classic server-side UI composition pattern rather than a separate frontend app.

8. Static assets are split into `app/static/css/style.css` and `app/static/js/main.js`, indicating the UI has some client-side behavior, but the main rendering model is still template-driven. The README’s “glassmorphic UI” and dark mode support are implemented here, not in a separate SPA framework.

9. Authentication is a distinct subsystem with its own views and routing. `auth.py`, `login.html`, and `register.html` suggest standard session-based access control around the analytics dashboard and data operations.

10. Operationally, the project includes `render.yaml` for Render deployment and `inspect_db.py` for local database inspection/debugging. That implies a deployment path to a hosted Flask app with a backing database, plus a small maintenance utility for examining persisted state.

11. For an architecture diagram, the key boundaries are: browser/UI → Flask routes → service layer → models/database, with ETL as the ingestion pipeline and ML/analytics as downstream consumers of cleaned historical data. The dashboard sits on top as the orchestration and visualization layer, while auth guards access to the rest of the system.

Main entry points: [`app/routes/dashboard.py`](https://github.com/muhammadshababb/ai-retail/blob/master/app/routes/dashboard.py) (Dashboard Routes), [`app/__init__.py`](https://github.com/muhammadshababb/ai-retail/blob/master/app/__init__.py) (App Init), [`app/routes/dataset.py`](https://github.com/muhammadshababb/ai-retail/blob/master/app/routes/dataset.py) (Dataset Routes), [`app/services/etl_service.py`](https://github.com/muhammadshababb/ai-retail/blob/master/app/services/etl_service.py) (ETL Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["App Package"]
  node_n_init["App Init<br/>flask app<br/>[__init__.py]"]
  node_n_auth["Auth Routes<br/>route handlers<br/>[auth.py]"]
  node_n_dash["Dashboard Routes<br/>route handlers<br/>[dashboard.py]"]
  node_n_dataset["Dataset Routes<br/>route handlers<br/>[dataset.py]"]
end

subgraph group_grp_ui["Presentation"]
  node_n_templates["Templates<br/>server-rendered views<br/>[base.html]"]
  node_n_dashboard_t["Dashboard View<br/>template<br/>[dashboard.html]"]
  node_n_upload_t["Upload View<br/>template<br/>[upload.html]"]
  node_n_auth_t["Auth Views<br/>templates<br/>[login.html]"]
  node_n_schema_t["Schema View<br/>template<br/>[schema.html]"]
  node_n_static_css["Styles<br/>css<br/>[style.css]"]
  node_n_static_js["Client JS<br/>script<br/>[main.js]"]
end

subgraph group_grp_service["Business Logic"]
  node_n_etl["ETL Service<br/>ingestion pipeline<br/>[etl_service.py]"]
  node_n_analytics["Analytics Service<br/>metrics engine"]
  node_n_ml["ML Service<br/>forecasting engine<br/>[ml_service.py]"]
  node_n_insight["Insight Service<br/>synthesis layer<br/>[insight_service.py]"]
end

subgraph group_grp_data["Persistence"]
  node_n_models[("Models<br/>persistence model<br/>[models.py]")]
end

subgraph group_grp_ops["Operations"]
  node_n_run["Run App<br/>entrypoint<br/>[run.py]"]
  node_n_inspect["DB Inspect<br/>[inspect_db.py]"]
  node_n_render["Render Config<br/>deployment<br/>[render.yaml]"]
end

node_n_user(("User<br/>actor"))

node_n_user -->|"sign in"| node_n_auth
node_n_user -->|"use app"| node_n_dash
node_n_user -->|"upload data"| node_n_upload_t
node_n_run -->|"starts"| node_n_init
node_n_init -->|"registers"| node_n_auth
node_n_init -->|"registers"| node_n_dash
node_n_init -->|"registers"| node_n_dataset
node_n_auth -->|"renders"| node_n_auth_t
node_n_dash -->|"renders"| node_n_dashboard_t
node_n_dash -->|"requests"| node_n_insight
node_n_dash -->|"requests"| node_n_analytics
node_n_dataset -->|"renders"| node_n_upload_t
node_n_dataset -->|"renders"| node_n_schema_t
node_n_dataset -->|"invokes"| node_n_etl
node_n_etl -->|"persists"| node_n_models
node_n_etl -->|"feeds"| node_n_analytics
node_n_etl -->|"feeds"| node_n_ml
node_n_analytics -->|"summarizes"| node_n_insight
node_n_ml -->|"predicts"| node_n_insight
node_n_auth -->|"reads/writes"| node_n_models
node_n_dash -->|"reads"| node_n_models
node_n_static_css -->|"styles"| node_n_dashboard_t
node_n_static_js -->|"enhances"| node_n_dashboard_t
node_n_inspect -.->|"inspects"| node_n_models
node_n_render -.->|"deploys"| node_n_run

click node_n_run "https://github.com/muhammadshababb/ai-retail/blob/master/run.py"
click node_n_init "https://github.com/muhammadshababb/ai-retail/blob/master/app/__init__.py"
click node_n_auth "https://github.com/muhammadshababb/ai-retail/blob/master/app/routes/auth.py"
click node_n_dash "https://github.com/muhammadshababb/ai-retail/blob/master/app/routes/dashboard.py"
click node_n_dataset "https://github.com/muhammadshababb/ai-retail/blob/master/app/routes/dataset.py"
click node_n_etl "https://github.com/muhammadshababb/ai-retail/blob/master/app/services/etl_service.py"
click node_n_analytics "https://github.com/muhammadshababb/ai-retail/blob/master/app/services/analytics_service.py"
click node_n_ml "https://github.com/muhammadshababb/ai-retail/blob/master/app/services/ml_service.py"
click node_n_insight "https://github.com/muhammadshababb/ai-retail/blob/master/app/services/insight_service.py"
click node_n_models "https://github.com/muhammadshababb/ai-retail/blob/master/app/models.py"
click node_n_templates "https://github.com/muhammadshababb/ai-retail/blob/master/app/templates/base.html"
click node_n_dashboard_t "https://github.com/muhammadshababb/ai-retail/blob/master/app/templates/dashboard.html"
click node_n_upload_t "https://github.com/muhammadshababb/ai-retail/blob/master/app/templates/upload.html"
click node_n_auth_t "https://github.com/muhammadshababb/ai-retail/blob/master/app/templates/login.html"
click node_n_schema_t "https://github.com/muhammadshababb/ai-retail/blob/master/app/templates/schema.html"
click node_n_static_css "https://github.com/muhammadshababb/ai-retail/blob/master/app/static/css/style.css"
click node_n_static_js "https://github.com/muhammadshababb/ai-retail/blob/master/app/static/js/main.js"
click node_n_inspect "https://github.com/muhammadshababb/ai-retail/blob/master/inspect_db.py"
click node_n_render "https://github.com/muhammadshababb/ai-retail/blob/master/render.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_init,node_n_auth,node_n_dash,node_n_dataset toneBlue
class node_n_templates,node_n_dashboard_t,node_n_upload_t,node_n_auth_t,node_n_schema_t,node_n_static_css,node_n_static_js toneAmber
class node_n_etl,node_n_analytics,node_n_ml,node_n_insight toneMint
class node_n_models toneRose
class node_n_run,node_n_inspect,node_n_render toneIndigo
class node_n_user toneNeutral
```

## Components

### App Package

Flask application package and HTTP boundary

- [App Init](https://github.com/muhammadshababb/ai-retail/blob/master/app/__init__.py): flask app · Flask app setup and wiring · `app/__init__.py`
- [Auth Routes](https://github.com/muhammadshababb/ai-retail/blob/master/app/routes/auth.py): route handlers · Login and registration endpoints · `app/routes/auth.py`
- [Dashboard Routes](https://github.com/muhammadshababb/ai-retail/blob/master/app/routes/dashboard.py): route handlers · Main analytics and dashboard endpoints · `app/routes/dashboard.py`
- [Dataset Routes](https://github.com/muhammadshababb/ai-retail/blob/master/app/routes/dataset.py): route handlers · Upload, ingestion, and schema endpoints · `app/routes/dataset.py`

### Presentation

Templates and static assets for server-rendered UI

- [Templates](https://github.com/muhammadshababb/ai-retail/blob/master/app/templates/base.html): server-rendered views · HTML pages rendered by Flask · `app/templates/base.html`
- [Dashboard View](https://github.com/muhammadshababb/ai-retail/blob/master/app/templates/dashboard.html): template · Main analytics page · `app/templates/dashboard.html`
- [Upload View](https://github.com/muhammadshababb/ai-retail/blob/master/app/templates/upload.html): template · Dataset upload page · `app/templates/upload.html`
- [Auth Views](https://github.com/muhammadshababb/ai-retail/blob/master/app/templates/login.html): templates · Login and registration pages · `app/templates/login.html`
- [Schema View](https://github.com/muhammadshababb/ai-retail/blob/master/app/templates/schema.html): template · Schema and inference page · `app/templates/schema.html`
- [Styles](https://github.com/muhammadshababb/ai-retail/blob/master/app/static/css/style.css): css · Global visual styling · `app/static/css/style.css`
- [Client JS](https://github.com/muhammadshababb/ai-retail/blob/master/app/static/js/main.js): script · Light client-side behavior · `app/static/js/main.js`

### Business Logic

Core ETL, analytics, forecasting, and insights

- [ETL Service](https://github.com/muhammadshababb/ai-retail/blob/master/app/services/etl_service.py): ingestion pipeline · Transforms uploaded datasets into normalized data · `app/services/etl_service.py`
- [Analytics Service](https://github.com/muhammadshababb/ai-retail/blob/master/app/services/analytics_service.py): metrics engine · Computes KPI-style analytics · `app/services/analytics_service.py`
- [ML Service](https://github.com/muhammadshababb/ai-retail/blob/master/app/services/ml_service.py): forecasting engine · Produces demand forecasts · `app/services/ml_service.py`
- [Insight Service](https://github.com/muhammadshababb/ai-retail/blob/master/app/services/insight_service.py): synthesis layer · Builds higher-level business insights · `app/services/insight_service.py`

### Persistence

Data models and database-facing utilities

- [Models](https://github.com/muhammadshababb/ai-retail/blob/master/app/models.py): persistence model · Shared data and schema contract · `app/models.py`

### Operations

Entrypoint and deployment helpers

- [Run App](https://github.com/muhammadshababb/ai-retail/blob/master/run.py): entrypoint · Application startup script · `run.py`
- [DB Inspect](https://github.com/muhammadshababb/ai-retail/blob/master/inspect_db.py): utility · Local database inspection tool · `inspect_db.py`
- [Render Config](https://github.com/muhammadshababb/ai-retail/blob/master/render.yaml): deployment · Hosted deployment configuration · `render.yaml`

### Other components

- **User**: actor · Browser user interacting with the app

## Connections

- User → Auth Routes: sign in · User accesses authentication views
- User → Dashboard Routes: use app · User interacts with dashboard and analytics flows
- User → Upload View: upload data · User submits datasets through the UI
- Run App → App Init: starts · Entrypoint boots the Flask app
- App Init → Auth Routes: registers · App wires auth routes
- App Init → Dashboard Routes: registers · App wires dashboard routes
- App Init → Dataset Routes: registers · App wires dataset routes
- Auth Routes → Auth Views: renders · Auth routes serve login and registration pages
- Dashboard Routes → Dashboard View: renders · Dashboard routes serve analytics pages
- Dashboard Routes → Insight Service: requests · Dashboard pulls synthesized insights
- Dashboard Routes → Analytics Service: requests · Dashboard pulls KPI analytics
- Dataset Routes → Upload View: renders · Dataset routes serve upload workflow pages
- Dataset Routes → Schema View: renders · Dataset routes serve schema-related pages
- Dataset Routes → ETL Service: invokes · Dataset routes send raw files into ETL
- ETL Service → Models: persists · ETL normalizes and stores dataset metadata/data
- ETL Service → Analytics Service: feeds · Clean data becomes input for analytics
- ETL Service → ML Service: feeds · Historical series are prepared for forecasting
- Analytics Service → Insight Service: summarizes · Analytics outputs are synthesized into insights
- ML Service → Insight Service: predicts · Forecast outputs contribute to insights
- Auth Routes → Models: reads/writes · Authentication depends on shared persistence models
- Dashboard Routes → Models: reads · Dashboard uses persisted application data
- Styles → Dashboard View: styles · Shared styling supports the server-rendered pages
- Client JS → Dashboard View: enhances · Client script adds lightweight UI behavior
- DB Inspect → Models: inspects · Utility reads database state through the model layer
- Render Config → Run App: deploys · Render config targets the app entrypoint
