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