# evereverton28/demandlens architecture

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

- Interactive diagram: https://gitdiagram.com/evereverton28/demandlens
- Repository: https://github.com/evereverton28/demandlens

## Overview

DemandLens turns a retailer’s transaction ledger into weekly demand analysis, forecasts and actionable stock decisions, then presents those results in a Flask dashboard. The main workflow is file import or ledger entry → analytics pipeline → stored analysis → dashboard/API. The README documents forecasting, backtesting, product profiling, risk, anomaly detection and recommendations; these remain distinct branches. The excerpts establish key pipeline, ingestion and persistence links; unsampled API and pipeline details limit some internal call edges.

Main entry points: [`analytics/pipeline.py`](https://github.com/evereverton28/demandlens/blob/main/analytics/pipeline.py) (Analysis orchestrator), [`analytics/evaluate.py`](https://github.com/evereverton28/demandlens/blob/main/analytics/evaluate.py) (Backtesting), [`app/api_analytics.py`](https://github.com/evereverton28/demandlens/blob/main/app/api_analytics.py) (Analytics API), [`app/db.py`](https://github.com/evereverton28/demandlens/blob/main/app/db.py) (SQLite access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Retailer app"]
  node_auth["Accounts and sessions<br/>[auth.py]"]
  node_data_api["Data API<br/>[api_data.py]"]
  node_analytics_api["Analytics API<br/>[api_analytics.py]"]
  node_dashboard["Dashboard views<br/>[views.py]"]
end

subgraph group_data["Ledger and imports"]
  node_db["SQLite access<br/>[db.py]"]
  node_ledger[("Transaction ledger<br/>[db.py]")]
  node_file_import["File importer<br/>[importer.py]"]
end

subgraph group_engine["Demand analytics"]
  node_ingest["File normalization<br/>[ingest.py]"]
  node_preprocess["Weekly demand panel<br/>[preprocess.py]"]
  node_profile["Product profiling<br/>[segmentation.py]"]
  node_trends["Trend analysis<br/>[trends.py]"]
  node_features["Forecast features<br/>[features.py]"]
  node_baselines["Baseline forecasts<br/>[baselines.py]"]
  node_forecasting["Global forecasting<br/>[forecasting.py]"]
  node_evaluation["Backtesting<br/>[evaluate.py]"]
  node_pipeline["Analysis orchestrator<br/>[pipeline.py]"]
end

subgraph group_results["Decision outputs"]
  node_risk["Stock risk<br/>[risk.py]"]
  node_anomalies["Anomaly detection<br/>[anomalies.py]"]
  node_recommend["Recommendations<br/>[recommend.py]"]
  node_saved["Saved results<br/>[saves.py]"]
end

node_retailer(("Retailer"))

node_retailer -->|"signs in"| node_auth
node_retailer -->|"manages data"| node_data_api
node_auth -->|"queries users"| node_db
node_data_api -->|"queries ledger"| node_db
node_file_import -->|"normalizes files"| node_ingest
node_file_import -->|"writes movements"| node_ledger
node_db -->|"accesses"| node_ledger
node_analytics_api -->|"runs analysis"| node_pipeline
node_pipeline -->|"loads movements"| node_ledger
node_pipeline -->|"builds panel"| node_preprocess
node_preprocess -->|"profiles demand"| node_profile
node_pipeline -->|"builds features"| node_features
node_pipeline -->|"backtests methods"| node_evaluation
node_evaluation -->|"scores methods"| node_baselines
node_evaluation -->|"evaluates model"| node_forecasting
node_features -->|"reads panel"| node_preprocess
node_pipeline -->|"selects forecasts"| node_baselines
node_pipeline -->|"forecasts demand"| node_forecasting
node_pipeline -->|"analyzes trends"| node_trends
node_pipeline -->|"estimates stock risk"| node_risk
node_pipeline -->|"detects anomalies"| node_anomalies
node_pipeline -->|"generates actions"| node_recommend
node_analytics_api -.->|"serves results"| node_saved
node_dashboard -.->|"requests analysis"| node_analytics_api
node_retailer -->|"views decisions"| node_dashboard

click node_auth "https://github.com/evereverton28/demandlens/blob/main/app/auth.py"
click node_data_api "https://github.com/evereverton28/demandlens/blob/main/app/api_data.py"
click node_analytics_api "https://github.com/evereverton28/demandlens/blob/main/app/api_analytics.py"
click node_dashboard "https://github.com/evereverton28/demandlens/blob/main/app/views.py"
click node_db "https://github.com/evereverton28/demandlens/blob/main/app/db.py"
click node_ledger "https://github.com/evereverton28/demandlens/blob/main/app/db.py"
click node_file_import "https://github.com/evereverton28/demandlens/blob/main/app/importer.py"
click node_ingest "https://github.com/evereverton28/demandlens/blob/main/analytics/ingest.py"
click node_preprocess "https://github.com/evereverton28/demandlens/blob/main/analytics/preprocess.py"
click node_profile "https://github.com/evereverton28/demandlens/blob/main/analytics/segmentation.py"
click node_trends "https://github.com/evereverton28/demandlens/blob/main/analytics/trends.py"
click node_features "https://github.com/evereverton28/demandlens/blob/main/analytics/features.py"
click node_baselines "https://github.com/evereverton28/demandlens/blob/main/analytics/baselines.py"
click node_forecasting "https://github.com/evereverton28/demandlens/blob/main/analytics/forecasting.py"
click node_evaluation "https://github.com/evereverton28/demandlens/blob/main/analytics/evaluate.py"
click node_pipeline "https://github.com/evereverton28/demandlens/blob/main/analytics/pipeline.py"
click node_risk "https://github.com/evereverton28/demandlens/blob/main/analytics/risk.py"
click node_anomalies "https://github.com/evereverton28/demandlens/blob/main/analytics/anomalies.py"
click node_recommend "https://github.com/evereverton28/demandlens/blob/main/analytics/recommend.py"
click node_saved "https://github.com/evereverton28/demandlens/blob/main/app/saves.py"

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_auth,node_data_api,node_analytics_api,node_dashboard toneBlue
class node_db,node_ledger,node_file_import toneAmber
class node_ingest,node_preprocess,node_profile,node_trends,node_features,node_baselines,node_forecasting,node_evaluation,node_pipeline toneMint
class node_risk,node_anomalies,node_recommend,node_saved toneRose
class node_retailer toneIndigo
```

## Components

### Retailer app

- [Accounts and sessions](https://github.com/evereverton28/demandlens/blob/main/app/auth.py): `app/auth.py`
- [Data API](https://github.com/evereverton28/demandlens/blob/main/app/api_data.py): `app/api_data.py`
- [Analytics API](https://github.com/evereverton28/demandlens/blob/main/app/api_analytics.py): `app/api_analytics.py`
- [Dashboard views](https://github.com/evereverton28/demandlens/blob/main/app/views.py): `app/views.py`

### Ledger and imports

- [SQLite access](https://github.com/evereverton28/demandlens/blob/main/app/db.py): `app/db.py`
- [Transaction ledger](https://github.com/evereverton28/demandlens/blob/main/app/db.py): `app/db.py`
- [File importer](https://github.com/evereverton28/demandlens/blob/main/app/importer.py): `app/importer.py`

### Demand analytics

- [File normalization](https://github.com/evereverton28/demandlens/blob/main/analytics/ingest.py): `analytics/ingest.py`
- [Weekly demand panel](https://github.com/evereverton28/demandlens/blob/main/analytics/preprocess.py): `analytics/preprocess.py`
- [Product profiling](https://github.com/evereverton28/demandlens/blob/main/analytics/segmentation.py): `analytics/segmentation.py`
- [Trend analysis](https://github.com/evereverton28/demandlens/blob/main/analytics/trends.py): `analytics/trends.py`
- [Forecast features](https://github.com/evereverton28/demandlens/blob/main/analytics/features.py): `analytics/features.py`
- [Baseline forecasts](https://github.com/evereverton28/demandlens/blob/main/analytics/baselines.py): `analytics/baselines.py`
- [Global forecasting](https://github.com/evereverton28/demandlens/blob/main/analytics/forecasting.py): `analytics/forecasting.py`
- [Backtesting](https://github.com/evereverton28/demandlens/blob/main/analytics/evaluate.py): `analytics/evaluate.py`
- [Analysis orchestrator](https://github.com/evereverton28/demandlens/blob/main/analytics/pipeline.py): `analytics/pipeline.py`

### Decision outputs

- [Stock risk](https://github.com/evereverton28/demandlens/blob/main/analytics/risk.py): `analytics/risk.py`
- [Anomaly detection](https://github.com/evereverton28/demandlens/blob/main/analytics/anomalies.py): `analytics/anomalies.py`
- [Recommendations](https://github.com/evereverton28/demandlens/blob/main/analytics/recommend.py): `analytics/recommend.py`
- [Saved results](https://github.com/evereverton28/demandlens/blob/main/app/saves.py): `app/saves.py`

### Other components

- **Retailer**

## Connections

- Retailer → Accounts and sessions: signs in (evidence: `app/auth.py`)
- Retailer → Data API: manages data (evidence: `app/api_data.py`)
- Accounts and sessions → SQLite access: queries users (evidence: `app/auth.py`)
- Data API → SQLite access: queries ledger (evidence: `app/api_data.py`)
- File importer → File normalization: normalizes files (evidence: `app/importer.py`)
- File importer → Transaction ledger: writes movements (evidence: `app/importer.py`)
- SQLite access → Transaction ledger: accesses (evidence: `app/db.py`)
- Analytics API → Analysis orchestrator: runs analysis (evidence: `analytics/pipeline.py`)
- Analysis orchestrator → Transaction ledger: loads movements (evidence: `analytics/pipeline.py`)
- Analysis orchestrator → Weekly demand panel: builds panel (evidence: `analytics/pipeline.py`)
- Weekly demand panel → Product profiling: profiles demand (evidence: `analytics/segmentation.py`)
- Analysis orchestrator → Forecast features: builds features (evidence: `analytics/pipeline.py`)
- Analysis orchestrator → Backtesting: backtests methods (evidence: `analytics/pipeline.py`)
- Backtesting → Baseline forecasts: scores methods (evidence: `analytics/evaluate.py`)
- Backtesting → Global forecasting: evaluates model (evidence: `analytics/evaluate.py`)
- Forecast features → Weekly demand panel: reads panel (evidence: `analytics/features.py`)
- Analysis orchestrator → Baseline forecasts: selects forecasts (evidence: `analytics/pipeline.py`)
- Analysis orchestrator → Global forecasting: forecasts demand (evidence: `analytics/pipeline.py`)
- Analysis orchestrator → Trend analysis: analyzes trends (evidence: `analytics/pipeline.py`)
- Analysis orchestrator → Stock risk: estimates stock risk (evidence: `analytics/pipeline.py`)
- Analysis orchestrator → Anomaly detection: detects anomalies (evidence: `analytics/pipeline.py`)
- Analysis orchestrator → Recommendations: generates actions (evidence: `analytics/pipeline.py`)
- Analytics API → Saved results: serves results
- Dashboard views → Analytics API: requests analysis
- Retailer → Dashboard views: views decisions (evidence: `app/views.py`)
