# gdeep01/kirana-insights architecture

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

- Interactive diagram: https://gitdiagram.com/gdeep01/kirana-insights
- Repository: https://github.com/gdeep01/kirana-insights

## Overview

1. **Repository shape**
   - This is a two-tier application called **Kirana Insights**.
   - The **frontend** is a React app built with Vite.
   - The **backend** is a Python API service with a database layer, analytical services, and a separate worker entrypoint.

2. **User-facing product flow**
   - Users interact through the frontend pages for **Upload**, **Dashboard**, **Forecast**, **Reorder**, and **Settings**.
   - These screens are organized around a retail-inventory decision workflow: ingest sales data, generate forecasts, inspect trends, and compute reorder recommendations.

3. **Frontend boundary**
   - `frontend/src/services/api.js` centralizes HTTP calls to the backend.
   - Page components in `frontend/src/pages/` are presentation-only consumers of backend data and actions.
   - This means the UI is a thin client: it does not own business logic, but renders the results of backend analytics and data operations.

4. **Backend application entry and API layer**
   - `backend/app/main.py` is the API startup entrypoint.
   - `backend/app/api/routes.py` is the main request-routing layer, likely exposing endpoints for upload, forecasting, reorder suggestions, and related summaries.
   - The backend is structured so the API layer is separate from the domain services, which is good for drawing a clean boundary between transport and business logic.

5. **Configuration and environment**
   - `backend/app/config/settings.py` and `backend/.env.example` indicate environment-driven configuration.
   - Typical responsibilities here are database connection details, service URLs, and runtime flags.
   - This makes the backend deployable in different environments without code changes.

6. **Persistence layer**
   - `backend/app/models/database.py` and `backend/app/models/models.py` define the database access and ORM entities.
   - `backend/app/schemas/schemas.py` provides the request/response shapes used by the API layer.
   - Alembic migrations under `backend/alembic/` show that schema evolution is tracked explicitly, so the database is a first-class part of the architecture.

7. **Sales data ingestion**
   - `backend/app/services/csv_upload.py` is the ingestion path for historical sales data.
   - The sample file `data/sample_sales.csv` and the upload page together suggest the system relies on sales history as the primary input for downstream analytics.
   - In an architecture diagram, this is the entry point from raw business data into the modeled dataset.

8. **Forecasting subsystem**
   - `backend/app/services/forecasting/` contains the forecasting engine.
   - `baseline.py` and `arima.py` imply multiple forecasting strategies, with `forecaster.py` acting as the orchestrator/selector.
   - This subsystem consumes historical sales data and outputs demand projections for the product experience and reorder logic.

9. **Reorder recommendation subsystem**
   - `backend/app/services/reorder/reorder.py` appears to turn forecasts into inventory recommendations.
   - This is the decision-support layer: it likely combines predicted demand with business constraints to produce optimal reorder quantities.
   - In the system flow, reorder recommendations depend on the forecasting output rather than raw data directly.

10. **Market and seasonality inputs**
   - `backend/app/services/mandi_prices.py` and `backend/app/services/festivals.py` indicate external or contextual signals.
   - These are likely used to enrich forecasting or ranking with market-trend and event-seasonality effects.
   - Architecturally, they are supporting data sources feeding the analytics pipeline.

11. **Asynchronous/background execution**
   - `backend/app/tasks.py` and `backend/app/worker.py` suggest that some processing can run outside the request/response cycle.
   - This is important for expensive jobs such as uploads, model computation, or data refreshes.
   - In diagrams, this should be shown as a backend worker path separate from the synchronous API path.

12. **Deployment and runtime**
   - The repo includes `Dockerfile` files for both backend and frontend, plus a top-level `docker-compose.yml`.
   - That indicates the project is intended to run as coordinated containers, with the frontend and backend deployed independently but connected over HTTP.
   - `backend/requirements.txt` and `frontend/package.json` define the runtime stacks: Python for the service layer and Node/Vite for the UI.

13. **Testing and validation**
   - `backend/tests/qa_scenario.py` suggests at least one end-to-end or scenario-based backend validation.
   - This is useful to represent as a quality gate around the API and analytics flow, especially since the application’s value depends on correct data processing.

14. **Key architecture summary**
   - The core data flow is: **CSV sales input and contextual market data → backend persistence/models → forecasting engine → reorder engine → API responses → frontend dashboards/pages**.
   - The main boundaries are **UI**, **API/service layer**, **database**, and **background worker/analytics**.

Main entry points: [`backend/app/api/routes.py`](https://github.com/gdeep01/kirana-insights/blob/main/backend/app/api/routes.py) (Routes), [`backend/app/services/forecasting/forecaster.py`](https://github.com/gdeep01/kirana-insights/blob/main/backend/app/services/forecasting/forecaster.py) (Forecaster), [`frontend/src/App.jsx`](https://github.com/gdeep01/kirana-insights/blob/main/frontend/src/App.jsx) (App shell), [`frontend/src/services/api.js`](https://github.com/gdeep01/kirana-insights/blob/main/frontend/src/services/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>React Vite entry<br/>[App.jsx]"]
  node_frontend_api["API client<br/>HTTP client<br/>[api.js]"]
  node_page_upload["Upload<br/>page<br/>[UploadPage.jsx]"]
  node_page_dashboard["Dashboard<br/>page<br/>[DashboardPage.jsx]"]
  node_page_forecast["Forecast<br/>page<br/>[ForecastPage.jsx]"]
  node_page_reorder["Reorder<br/>page<br/>[ReorderPage.jsx]"]
  node_page_settings["Settings<br/>page<br/>[SettingsPage.jsx]"]
end

subgraph group_backend["Backend"]
  node_api_main["API entry<br/>FastAPI startup<br/>[main.py]"]
  node_api_routes["Routes<br/>HTTP routing<br/>[routes.py]"]
  node_settings["Config<br/>[settings.py]"]
  node_database[("Database<br/>db access<br/>[database.py]")]
  node_models["Models<br/>ORM entities<br/>[models.py]"]
  node_schemas["Schemas<br/>API contracts<br/>[schemas.py]"]
  node_csv_upload["CSV upload<br/>ingestion service<br/>[csv_upload.py]"]
  node_forecaster["Forecaster<br/>analytics orchestrator<br/>[forecaster.py]"]
  node_baseline["Baseline<br/>forecast model<br/>[baseline.py]"]
  node_arima["ARIMA<br/>forecast model<br/>[arima.py]"]
  node_reorder["Reorder engine<br/>decision service<br/>[reorder.py]"]
  node_context_signals["Context signals<br/>external inputs<br/>[mandi_prices.py]"]
  node_tasks["Tasks<br/>async jobs<br/>[tasks.py]"]
  node_worker["Worker<br/>background runtime<br/>[worker.py]"]
  node_migrations["Migrations<br/>schema evolution"]
  node_qa["QA scenario<br/>validation<br/>[qa_scenario.py]"]
end

subgraph group_ops["Runtime"]
  node_sample_sales["Sample sales<br/>input dataset<br/>[sample_sales.csv]"]
  node_compose["Compose<br/>deployment<br/>[docker-compose.yml]"]
end

node_frontend_app -->|"navigates to"| node_page_upload
node_frontend_app -->|"navigates to"| node_page_dashboard
node_frontend_app -->|"navigates to"| node_page_forecast
node_frontend_app -->|"navigates to"| node_page_reorder
node_frontend_app -->|"navigates to"| node_page_settings
node_page_upload -->|"uses"| node_frontend_api
node_page_dashboard -->|"uses"| node_frontend_api
node_page_forecast -->|"uses"| node_frontend_api
node_page_reorder -->|"uses"| node_frontend_api
node_page_settings -->|"uses"| node_frontend_api
node_frontend_api -->|"HTTP"| node_api_routes
node_api_main -->|"mounts"| node_api_routes
node_api_main -->|"loads"| node_settings
node_api_main -->|"connects"| node_database
node_api_routes -->|"validates"| node_schemas
node_api_routes -->|"delegates"| node_csv_upload
node_api_routes -->|"delegates"| node_forecaster
node_api_routes -->|"delegates"| node_reorder
node_csv_upload -->|"writes"| node_models
node_csv_upload -->|"stores"| node_database
node_csv_upload -.->|"queues"| node_tasks
node_forecaster -->|"selects"| node_baseline
node_forecaster -->|"selects"| node_arima
node_forecaster -->|"enriches with"| node_context_signals
node_forecaster -->|"reads"| node_models
node_reorder -->|"consumes"| node_forecaster
node_reorder -->|"reads"| node_models
node_tasks -->|"runs on"| node_worker
node_migrations -->|"evolves"| node_database
node_qa -.->|"checks"| node_api_routes
node_qa -.->|"checks"| node_forecaster
node_sample_sales -->|"feeds"| node_csv_upload
node_compose -->|"deploys"| node_frontend_app
node_compose -->|"deploys"| node_api_main
node_compose -->|"deploys"| node_worker

click node_frontend_app "https://github.com/gdeep01/kirana-insights/blob/main/frontend/src/App.jsx"
click node_frontend_api "https://github.com/gdeep01/kirana-insights/blob/main/frontend/src/services/api.js"
click node_page_upload "https://github.com/gdeep01/kirana-insights/blob/main/frontend/src/pages/UploadPage.jsx"
click node_page_dashboard "https://github.com/gdeep01/kirana-insights/blob/main/frontend/src/pages/DashboardPage.jsx"
click node_page_forecast "https://github.com/gdeep01/kirana-insights/blob/main/frontend/src/pages/ForecastPage.jsx"
click node_page_reorder "https://github.com/gdeep01/kirana-insights/blob/main/frontend/src/pages/ReorderPage.jsx"
click node_page_settings "https://github.com/gdeep01/kirana-insights/blob/main/frontend/src/pages/SettingsPage.jsx"
click node_api_main "https://github.com/gdeep01/kirana-insights/blob/main/backend/app/main.py"
click node_api_routes "https://github.com/gdeep01/kirana-insights/blob/main/backend/app/api/routes.py"
click node_settings "https://github.com/gdeep01/kirana-insights/blob/main/backend/app/config/settings.py"
click node_database "https://github.com/gdeep01/kirana-insights/blob/main/backend/app/models/database.py"
click node_models "https://github.com/gdeep01/kirana-insights/blob/main/backend/app/models/models.py"
click node_schemas "https://github.com/gdeep01/kirana-insights/blob/main/backend/app/schemas/schemas.py"
click node_csv_upload "https://github.com/gdeep01/kirana-insights/blob/main/backend/app/services/csv_upload.py"
click node_forecaster "https://github.com/gdeep01/kirana-insights/blob/main/backend/app/services/forecasting/forecaster.py"
click node_baseline "https://github.com/gdeep01/kirana-insights/blob/main/backend/app/services/forecasting/baseline.py"
click node_arima "https://github.com/gdeep01/kirana-insights/blob/main/backend/app/services/forecasting/arima.py"
click node_reorder "https://github.com/gdeep01/kirana-insights/blob/main/backend/app/services/reorder/reorder.py"
click node_context_signals "https://github.com/gdeep01/kirana-insights/blob/main/backend/app/services/mandi_prices.py"
click node_tasks "https://github.com/gdeep01/kirana-insights/blob/main/backend/app/tasks.py"
click node_worker "https://github.com/gdeep01/kirana-insights/blob/main/backend/app/worker.py"
click node_migrations "https://github.com/gdeep01/kirana-insights/blob/main/backend/alembic/versions/63299f57d02f_initial_migration.py"
click node_qa "https://github.com/gdeep01/kirana-insights/blob/main/backend/tests/qa_scenario.py"
click node_sample_sales "https://github.com/gdeep01/kirana-insights/blob/main/data/sample_sales.csv"
click node_compose "https://github.com/gdeep01/kirana-insights/blob/main/docker-compose.yml"

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_frontend_app,node_frontend_api,node_page_upload,node_page_dashboard,node_page_forecast,node_page_reorder,node_page_settings toneBlue
class node_api_main,node_api_routes,node_settings,node_database,node_models,node_schemas,node_csv_upload,node_forecaster,node_baseline,node_arima,node_reorder,node_context_signals,node_tasks,node_worker,node_migrations,node_qa toneAmber
class node_sample_sales,node_compose toneMint
```

## Components

### Frontend

React/Vite UI and API client

- [App shell](https://github.com/gdeep01/kirana-insights/blob/main/frontend/src/App.jsx): React Vite entry · UI root and routing shell · `frontend/src/App.jsx`
- [API client](https://github.com/gdeep01/kirana-insights/blob/main/frontend/src/services/api.js): HTTP client · Central backend request wrapper · `frontend/src/services/api.js`
- [Upload](https://github.com/gdeep01/kirana-insights/blob/main/frontend/src/pages/UploadPage.jsx): page · Sales data ingestion screen · `frontend/src/pages/UploadPage.jsx`
- [Dashboard](https://github.com/gdeep01/kirana-insights/blob/main/frontend/src/pages/DashboardPage.jsx): page · Inventory and trend overview · `frontend/src/pages/DashboardPage.jsx`
- [Forecast](https://github.com/gdeep01/kirana-insights/blob/main/frontend/src/pages/ForecastPage.jsx): page · Demand projection screen · `frontend/src/pages/ForecastPage.jsx`
- [Reorder](https://github.com/gdeep01/kirana-insights/blob/main/frontend/src/pages/ReorderPage.jsx): page · Inventory recommendation screen · `frontend/src/pages/ReorderPage.jsx`
- [Settings](https://github.com/gdeep01/kirana-insights/blob/main/frontend/src/pages/SettingsPage.jsx): page · Application configuration screen · `frontend/src/pages/SettingsPage.jsx`

### Backend

Python API, services, database, and worker

- [API entry](https://github.com/gdeep01/kirana-insights/blob/main/backend/app/main.py): FastAPI startup · Backend application bootstrap · `backend/app/main.py`
- [Routes](https://github.com/gdeep01/kirana-insights/blob/main/backend/app/api/routes.py): HTTP routing · Primary request dispatch layer · `backend/app/api/routes.py`
- [Config](https://github.com/gdeep01/kirana-insights/blob/main/backend/app/config/settings.py): env config · Runtime settings and environment binding · `backend/app/config/settings.py`
- [Database](https://github.com/gdeep01/kirana-insights/blob/main/backend/app/models/database.py): db access · Connection and persistence setup · `backend/app/models/database.py`
- [Models](https://github.com/gdeep01/kirana-insights/blob/main/backend/app/models/models.py): ORM entities · Persistent domain objects · `backend/app/models/models.py`
- [Schemas](https://github.com/gdeep01/kirana-insights/blob/main/backend/app/schemas/schemas.py): API contracts · Request and response shapes · `backend/app/schemas/schemas.py`
- [CSV upload](https://github.com/gdeep01/kirana-insights/blob/main/backend/app/services/csv_upload.py): ingestion service · Imports sales history into the system · `backend/app/services/csv_upload.py`
- [Forecaster](https://github.com/gdeep01/kirana-insights/blob/main/backend/app/services/forecasting/forecaster.py): analytics orchestrator · Selects and runs forecasting strategies · `backend/app/services/forecasting/forecaster.py`
- [Baseline](https://github.com/gdeep01/kirana-insights/blob/main/backend/app/services/forecasting/baseline.py): forecast model · Simple demand forecast strategy · `backend/app/services/forecasting/baseline.py`
- [ARIMA](https://github.com/gdeep01/kirana-insights/blob/main/backend/app/services/forecasting/arima.py): forecast model · Time-series forecasting strategy · `backend/app/services/forecasting/arima.py`
- [Reorder engine](https://github.com/gdeep01/kirana-insights/blob/main/backend/app/services/reorder/reorder.py): decision service · Turns forecasts into inventory recommendations · `backend/app/services/reorder/reorder.py`
- [Context signals](https://github.com/gdeep01/kirana-insights/blob/main/backend/app/services/mandi_prices.py): external inputs · Market prices and festival seasonality · `backend/app/services/mandi_prices.py`
- [Tasks](https://github.com/gdeep01/kirana-insights/blob/main/backend/app/tasks.py): async jobs · Background job definitions · `backend/app/tasks.py`
- [Worker](https://github.com/gdeep01/kirana-insights/blob/main/backend/app/worker.py): background runtime · Separate async execution entrypoint · `backend/app/worker.py`
- [Migrations](https://github.com/gdeep01/kirana-insights/blob/main/backend/alembic/versions/63299f57d02f_initial_migration.py): schema evolution · Alembic database changes · `backend/alembic/versions/63299f57d02f_initial_migration.py`
- [QA scenario](https://github.com/gdeep01/kirana-insights/blob/main/backend/tests/qa_scenario.py): validation · Scenario-based backend check · `backend/tests/qa_scenario.py`

### Runtime

Container and deployment boundary

- [Sample sales](https://github.com/gdeep01/kirana-insights/blob/main/data/sample_sales.csv): input dataset · Representative CSV sales history · `data/sample_sales.csv`
- [Compose](https://github.com/gdeep01/kirana-insights/blob/main/docker-compose.yml): deployment · Container orchestration for frontend and backend · `docker-compose.yml`

## Connections

- App shell → Upload: navigates to · App shell hosts product screens
- App shell → Dashboard: navigates to · App shell hosts product screens
- App shell → Forecast: navigates to · App shell hosts product screens
- App shell → Reorder: navigates to · App shell hosts product screens
- App shell → Settings: navigates to · App shell hosts product screens
- Upload → API client: uses · Upload screen calls backend APIs
- Dashboard → API client: uses · Dashboard fetches analytics data
- Forecast → API client: uses · Forecast screen fetches projections
- Reorder → API client: uses · Reorder screen fetches recommendations
- Settings → API client: uses · Settings screen reads and writes config
- API client → Routes: HTTP · All UI requests terminate at backend routes
- API entry → Routes: mounts · Application bootstraps the routing layer
- API entry → Config: loads · Startup reads environment settings
- API entry → Database: connects · Startup initializes persistence access
- Routes → Schemas: validates · Routes use shared request and response shapes
- Routes → CSV upload: delegates · Upload endpoints invoke ingestion service
- Routes → Forecaster: delegates · Forecast endpoints invoke analytics orchestrator
- Routes → Reorder engine: delegates · Reorder endpoints invoke decision service
- CSV upload → Models: writes · Imported sales data is persisted in ORM models
- CSV upload → Database: stores · Ingestion path persists records
- CSV upload → Tasks: queues · Heavy ingestion can be offloaded
- Forecaster → Baseline: selects · One forecasting strategy is baseline
- Forecaster → ARIMA: selects · One forecasting strategy is ARIMA
- Forecaster → Context signals: enriches with · Forecasting can use market and festival context
- Forecaster → Models: reads · Uses historical sales data from persistence
- Reorder engine → Forecaster: consumes · Reorder logic depends on forecast output
- Reorder engine → Models: reads · Uses stored inventory and sales state
- Tasks → Worker: runs on · Background jobs execute in separate worker process
- Migrations → Database: evolves · Schema migrations track database changes
- QA scenario → Routes: checks · Scenario validation exercises the API flow
- QA scenario → Forecaster: checks · Validation covers analytics behavior
- Sample sales → CSV upload: feeds · Example sales input for ingestion flow
- Compose → App shell: deploys · Compose orchestrates the frontend service
- Compose → API entry: deploys · Compose orchestrates the backend service
- Compose → Worker: deploys · Compose can run the worker separately
