How gdeep01/kirana-insights works
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: routes.py Routes · forecaster.py Forecaster · App.jsx App shell · api.js API client
Components 25
Frontend
React/Vite UI and API client
- App shell · UI root and routing shell
frontend/src/App.jsx - API client · Central backend request wrapper
frontend/src/services/api.js - Upload · Sales data ingestion screen
frontend/src/pages/UploadPage.jsx - Dashboard · Inventory and trend overview
frontend/src/pages/DashboardPage.jsx - Forecast · Demand projection screen
frontend/src/pages/ForecastPage.jsx - Reorder · Inventory recommendation screen
frontend/src/pages/ReorderPage.jsx - Settings · Application configuration screen
frontend/src/pages/SettingsPage.jsx
Backend
Python API, services, database, and worker
- API entry · Backend application bootstrap
backend/app/main.py - Routes · Primary request dispatch layer
backend/app/api/routes.py - Config · Runtime settings and environment binding
backend/app/config/settings.py - Database · Connection and persistence setup
backend/app/models/database.py - Models · Persistent domain objects
backend/app/models/models.py - Schemas · Request and response shapes
backend/app/schemas/schemas.py - CSV upload · Imports sales history into the system
backend/app/services/csv_upload.py - Forecaster · Selects and runs forecasting strategies
backend/app/services/forecasting/forecaster.py - Baseline · Simple demand forecast strategy
backend/app/services/forecasting/baseline.py - ARIMA · Time-series forecasting strategy
backend/app/services/forecasting/arima.py - Reorder engine · Turns forecasts into inventory recommendations
backend/app/services/reorder/reorder.py - Context signals · Market prices and festival seasonality
backend/app/services/mandi_prices.py - Tasks · Background job definitions
backend/app/tasks.py - Worker · Separate async execution entrypoint
backend/app/worker.py - Migrations · Alembic database changes
backend/alembic/versions/63299f57d02f_initial_migration.py - QA scenario · Scenario-based backend check
backend/tests/qa_scenario.py
Runtime
Container and deployment boundary
- Sample sales · Representative CSV sales history
data/sample_sales.csv - Compose · Container orchestration for frontend and backend
docker-compose.yml
Connections 35
- 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