How muhammadshababb/ai-retail works
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: dashboard.py Dashboard Routes · __init__.py App Init · dataset.py Dataset Routes · etl_service.py ETL Service
Components 20
App Package
Flask application package and HTTP boundary
- App Init · Flask app setup and wiring
app/__init__.py - Auth Routes · Login and registration endpoints
app/routes/auth.py - Dashboard Routes · Main analytics and dashboard endpoints
app/routes/dashboard.py - Dataset Routes · Upload, ingestion, and schema endpoints
app/routes/dataset.py
Presentation
Templates and static assets for server-rendered UI
- Templates · HTML pages rendered by Flask
app/templates/base.html - Dashboard View · Main analytics page
app/templates/dashboard.html - Upload View · Dataset upload page
app/templates/upload.html - Auth Views · Login and registration pages
app/templates/login.html - Schema View · Schema and inference page
app/templates/schema.html - Styles · Global visual styling
app/static/css/style.css - Client JS · Light client-side behavior
app/static/js/main.js
Business Logic
Core ETL, analytics, forecasting, and insights
- ETL Service · Transforms uploaded datasets into normalized data
app/services/etl_service.py - Analytics Service · Computes KPI-style analytics
app/services/analytics_service.py - ML Service · Produces demand forecasts
app/services/ml_service.py - Insight Service · Builds higher-level business insights
app/services/insight_service.py
Persistence
Data models and database-facing utilities
- Models · Shared data and schema contract
app/models.py
Operations
Entrypoint and deployment helpers
- Run App · Application startup script
run.py - DB Inspect · Local database inspection tool
inspect_db.py - Render Config · Hosted deployment configuration
render.yaml
Other components
- User · Browser user interacting with the app
Connections 25
- 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