# ayushman-hss/steptosales architecture

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

- Interactive diagram: https://gitdiagram.com/ayushman-hss/steptosales
- Repository: https://github.com/ayushman-hss/steptosales

## Overview

StepToSales is a retail-intelligence app for neighbourhood shops. An operator signs in, then uses dashboard analytics, bundle recommendations, group-buying pools, a live till/day view, and phone alerts with shop-specific questions. The browser’s typed API client calls FastAPI routes, which delegate to analytics and domain services backed by PostgreSQL; live events also drive the changing day view. The README documents the major capabilities; some routes and services were not sampled, so those branches are included where documented, with uncertain implementation links omitted.

Main entry points: [`backend/app/main.py`](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/main.py) (FastAPI application), [`frontend/src/App.tsx`](https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/App.tsx) (React app), [`frontend/src/api.ts`](https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/api.ts) (Typed API client), [`backend/app/routers/dashboard.py`](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/dashboard.py) (Dashboard route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Shop interface"]
  node_app["React app<br/>[App.tsx]"]
  node_dashpage["Dashboard<br/>[DashboardPage.tsx]"]
  node_till["Phone till<br/>[TillPage.tsx]"]
  node_bundlesui["Bundle review<br/>[BundlePage.tsx]"]
  node_poolsui["Pool management<br/>[PoolsPage.tsx]"]
  node_alertsui["Alerts and questions<br/>[AlertsPage.tsx]"]
  node_authui["Session state<br/>[auth.ts]"]
  node_client["Typed API client<br/>[api.ts]"]
end

subgraph group_api["API and access"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_authroutes["Authentication routes<br/>[auth.py]"]
  node_dashboardroute["Dashboard route<br/>[dashboard.py]"]
  node_productroutes["Product routes<br/>[products.py]"]
  node_bundleroutes["Bundle routes<br/>[bundles.py]"]
  node_poolroutes["Pool routes<br/>[pools.py]"]
  node_liveroutes["Live routes<br/>[live.py]"]
  node_alertroutes["Alert routes<br/>[alerts.py]"]
  node_assistantroutes["Assistant routes<br/>[assistant.py]"]
  node_access["Store access check<br/>[dependencies.py]"]
  node_authservice["Authentication service<br/>[auth.py]"]
end

subgraph group_analytics["Retail analytics"]
  node_metrics["Retail metrics<br/>[metrics.py]"]
  node_insights["Retail insights<br/>[insights.py]"]
  node_bundlelogic["Bundle pricing and analysis<br/>[bundles.py]"]
end

subgraph group_pooling["Group buying"]
  node_pooldomain["Pool domain<br/>[pool.py]"]
  node_allocation["Saving allocation<br/>[allocation.py]"]
  node_tiers["Supplier price tiers<br/>[tiers.py]"]
  node_poolrepo["Pool persistence adapter<br/>[repository.py]"]
end

subgraph group_livealerts["Live and alerts"]
  node_liveengine["Live event engine<br/>[engine.py]"]
  node_simulator["Day simulator<br/>[simulator.py]"]
  node_runner["Live runner<br/>[runner.py]"]
  node_pace["Trading pace<br/>[pace.py]"]
  node_today["Today view<br/>[today.py]"]
  node_alertservice["Alert watcher and bot<br/>[service.py]"]
end

subgraph group_persistence["Persistence"]
  node_db[("PostgreSQL<br/>database")]
end

node_operator(("Shop operator"))

node_operator -->|"uses"| node_app
node_app -->|"restores session"| node_authui
node_app -->|"routes to"| node_dashpage
node_app -->|"routes to"| node_till
node_app -->|"routes to"| node_bundlesui
node_app -->|"routes to"| node_poolsui
node_app -->|"routes to"| node_alertsui
node_authui -->|"stores credentials for"| node_client
node_dashpage -->|"requests data via"| node_client
node_till -->|"submits bills via"| node_client
node_bundlesui -.->|"manages bundles via"| node_client
node_poolsui -->|"manages pools via"| node_client
node_alertsui -->|"requests alerts via"| node_client
node_client -->|"calls API"| node_fastapi
node_fastapi -->|"registers"| node_authroutes
node_fastapi -->|"registers"| node_dashboardroute
node_fastapi -->|"registers"| node_liveroutes
node_fastapi -->|"registers"| node_alertroutes
node_fastapi -->|"registers"| node_assistantroutes
node_fastapi -->|"registers"| node_productroutes
node_fastapi -->|"registers"| node_bundleroutes
node_fastapi -->|"registers"| node_poolroutes
node_authroutes -->|"uses"| node_authservice
node_access -->|"resolves sessions with"| node_authservice
node_dashboardroute -->|"calculates"| node_metrics
node_dashboardroute -->|"derives observations with"| node_insights
node_bundleroutes -.->|"uses"| node_bundlelogic
node_poolroutes -->|"loads and records via"| node_poolrepo
node_poolrepo -->|"reconstructs"| node_pooldomain
node_pooldomain -->|"allocates savings with"| node_allocation
node_pooldomain -->|"prices against"| node_tiers
node_poolrepo -->|"loads tier tables"| node_tiers
node_liveroutes -.->|"uses"| node_liveengine
node_fastapi -->|"starts at startup"| node_runner
node_liveengine -->|"simulates with"| node_simulator
node_dashboardroute -->|"calculates pace with"| node_pace
node_today -->|"uses"| node_pace
node_alertroutes -.->|"uses"| node_alertservice
node_fastapi -->|"starts when enabled"| node_alertservice
node_alertservice -->|"computes live view with"| node_today
node_assistantroutes -.->|"answers questions through"| node_alertservice
node_fastapi -->|"initializes"| node_db
node_poolrepo -.->|"reads and writes through"| node_db

click node_app "https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/App.tsx"
click node_dashpage "https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/pages/DashboardPage.tsx"
click node_till "https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/pages/TillPage.tsx"
click node_bundlesui "https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/pages/BundlePage.tsx"
click node_poolsui "https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/pages/PoolsPage.tsx"
click node_alertsui "https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/pages/AlertsPage.tsx"
click node_authui "https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/auth.ts"
click node_client "https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/api.ts"
click node_fastapi "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/main.py"
click node_authroutes "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/auth.py"
click node_dashboardroute "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/dashboard.py"
click node_productroutes "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/products.py"
click node_bundleroutes "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/bundles.py"
click node_poolroutes "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/pools.py"
click node_liveroutes "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/live.py"
click node_alertroutes "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/alerts.py"
click node_assistantroutes "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/assistant.py"
click node_access "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/dependencies.py"
click node_authservice "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/auth.py"
click node_metrics "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/metrics.py"
click node_insights "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/insights.py"
click node_bundlelogic "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/bundles.py"
click node_pooldomain "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/pooling/pool.py"
click node_allocation "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/pooling/allocation.py"
click node_tiers "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/pooling/tiers.py"
click node_poolrepo "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/pooling/repository.py"
click node_liveengine "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/live/engine.py"
click node_simulator "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/live/simulator.py"
click node_runner "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/live/runner.py"
click node_pace "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/live/pace.py"
click node_today "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/live/today.py"
click node_alertservice "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/alerts/service.py"
click node_db "https://github.com/ayushman-hss/steptosales/blob/main/backend/app/db.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_app,node_dashpage,node_till,node_bundlesui,node_poolsui,node_alertsui,node_authui,node_client toneBlue
class node_fastapi,node_authroutes,node_dashboardroute,node_productroutes,node_bundleroutes,node_poolroutes,node_liveroutes,node_alertroutes,node_assistantroutes,node_access,node_authservice toneAmber
class node_metrics,node_insights,node_bundlelogic toneMint
class node_pooldomain,node_allocation,node_tiers,node_poolrepo toneRose
class node_liveengine,node_simulator,node_runner,node_pace,node_today,node_alertservice,node_operator toneIndigo
class node_db toneTeal
```

## Components

### Shop interface

- [React app](https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Dashboard](https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/pages/DashboardPage.tsx): `frontend/src/pages/DashboardPage.tsx`
- [Phone till](https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/pages/TillPage.tsx): `frontend/src/pages/TillPage.tsx`
- [Bundle review](https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/pages/BundlePage.tsx): `frontend/src/pages/BundlePage.tsx`
- [Pool management](https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/pages/PoolsPage.tsx): `frontend/src/pages/PoolsPage.tsx`
- [Alerts and questions](https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/pages/AlertsPage.tsx): `frontend/src/pages/AlertsPage.tsx`
- [Session state](https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/auth.ts): `frontend/src/auth.ts`
- [Typed API client](https://github.com/ayushman-hss/steptosales/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### API and access

- [FastAPI application](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication routes](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Dashboard route](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/dashboard.py): `backend/app/routers/dashboard.py`
- [Product routes](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/products.py): `backend/app/routers/products.py`
- [Bundle routes](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/bundles.py): `backend/app/routers/bundles.py`
- [Pool routes](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/pools.py): `backend/app/routers/pools.py`
- [Live routes](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/live.py): `backend/app/routers/live.py`
- [Alert routes](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/alerts.py): `backend/app/routers/alerts.py`
- [Assistant routes](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/routers/assistant.py): `backend/app/routers/assistant.py`
- [Store access check](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/dependencies.py): `backend/app/dependencies.py`
- [Authentication service](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/auth.py): `backend/app/services/auth.py`

### Retail analytics

- [Retail metrics](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/metrics.py): `backend/app/services/metrics.py`
- [Retail insights](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/insights.py): `backend/app/services/insights.py`
- [Bundle pricing and analysis](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/bundles.py): `backend/app/services/bundles.py`

### Group buying

- [Pool domain](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/pooling/pool.py): `backend/app/services/pooling/pool.py`
- [Saving allocation](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/pooling/allocation.py): `backend/app/services/pooling/allocation.py`
- [Supplier price tiers](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/pooling/tiers.py): `backend/app/services/pooling/tiers.py`
- [Pool persistence adapter](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/pooling/repository.py): `backend/app/services/pooling/repository.py`

### Live and alerts

- [Live event engine](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/live/engine.py): `backend/app/services/live/engine.py`
- [Day simulator](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/live/simulator.py): `backend/app/services/live/simulator.py`
- [Live runner](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/live/runner.py): `backend/app/services/live/runner.py`
- [Trading pace](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/live/pace.py): `backend/app/services/live/pace.py`
- [Today view](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/live/today.py): `backend/app/services/live/today.py`
- [Alert watcher and bot](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/services/alerts/service.py): `backend/app/services/alerts/service.py`

### Persistence

- [PostgreSQL](https://github.com/ayushman-hss/steptosales/blob/main/backend/app/db.py): database · `backend/app/db.py`

### Other components

- **Shop operator**

## Connections

- Shop operator → React app: uses
- React app → Session state: restores session (evidence: `frontend/src/App.tsx`)
- React app → Dashboard: routes to (evidence: `frontend/src/App.tsx`)
- React app → Phone till: routes to (evidence: `frontend/src/App.tsx`)
- React app → Bundle review: routes to (evidence: `frontend/src/App.tsx`)
- React app → Pool management: routes to (evidence: `frontend/src/App.tsx`)
- React app → Alerts and questions: routes to (evidence: `frontend/src/App.tsx`)
- Session state → Typed API client: stores credentials for (evidence: `frontend/src/auth.ts`)
- Dashboard → Typed API client: requests data via (evidence: `frontend/src/pages/DashboardPage.tsx`)
- Phone till → Typed API client: submits bills via (evidence: `frontend/src/pages/TillPage.tsx`)
- Bundle review → Typed API client: manages bundles via
- Pool management → Typed API client: manages pools via (evidence: `frontend/src/pages/PoolsPage.tsx`)
- Alerts and questions → Typed API client: requests alerts via (evidence: `frontend/src/pages/AlertsPage.tsx`)
- Typed API client → FastAPI application: calls API (evidence: `frontend/src/api.ts`)
- FastAPI application → Authentication routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Dashboard route: registers (evidence: `backend/app/main.py`)
- FastAPI application → Live routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Alert routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Assistant routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Product routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Bundle routes: registers (evidence: `backend/app/main.py`)
- FastAPI application → Pool routes: registers (evidence: `backend/app/main.py`)
- Authentication routes → Authentication service: uses (evidence: `backend/app/routers/auth.py`)
- Store access check → Authentication service: resolves sessions with (evidence: `backend/app/dependencies.py`)
- Dashboard route → Retail metrics: calculates (evidence: `backend/app/routers/dashboard.py`)
- Dashboard route → Retail insights: derives observations with (evidence: `backend/app/routers/dashboard.py`)
- Bundle routes → Bundle pricing and analysis: uses
- Pool routes → Pool persistence adapter: loads and records via (evidence: `backend/app/routers/pools.py`)
- Pool persistence adapter → Pool domain: reconstructs (evidence: `backend/app/services/pooling/repository.py`)
- Pool domain → Saving allocation: allocates savings with (evidence: `backend/app/services/pooling/pool.py`)
- Pool domain → Supplier price tiers: prices against (evidence: `backend/app/services/pooling/pool.py`)
- Pool persistence adapter → Supplier price tiers: loads tier tables (evidence: `backend/app/services/pooling/repository.py`)
- Live routes → Live event engine: uses
- FastAPI application → Live runner: starts at startup (evidence: `backend/app/main.py`)
- Live event engine → Day simulator: simulates with (evidence: `backend/app/services/live/engine.py`)
- Dashboard route → Trading pace: calculates pace with (evidence: `backend/app/routers/dashboard.py`)
- Today view → Trading pace: uses (evidence: `backend/app/services/live/today.py`)
- Alert routes → Alert watcher and bot: uses
- FastAPI application → Alert watcher and bot: starts when enabled (evidence: `backend/app/main.py`)
- Alert watcher and bot → Today view: computes live view with (evidence: `backend/app/services/alerts/service.py`)
- Assistant routes → Alert watcher and bot: answers questions through
- FastAPI application → PostgreSQL: initializes (evidence: `backend/app/main.py`)
- Pool persistence adapter → PostgreSQL: reads and writes through