How trankhanhnamhoccode/shelfcash_backend works
ShelfCash is a FastAPI backend for importing store data, forecasting demand, planning ingredients and procurement, and providing decision assistance. The documented workflow runs from imports and operational data through forecasting and ingredient/procurement planning to a persisted Decision Run, then serves brief, explanation, and what-if read models. The graph distinguishes API orchestration, domain processing, forecasting, and decision presentation. Several runtime modules are unsampled; their components are included where supported by the tree and README, but uncertain internal links are omitted or marked unverified.
Main entry points: import_service.py Import service · inference_pipeline.py Forecast inference · main.py FastAPI app · decision_planning_service.py Decision run
Components 22
API and imports
- FastAPI app
app/main.py - Import routes
app/api/imports.py - Import service
app/services/import_service.py - Sheet ingestion
app/core/ingestion_pipeline.py - Forecast routes
app/api/forecast.py
Store operations
- Catalog and recipes
app/services/catalog_service.py - Operational data
app/services/operational_service.py
Forecast and demand
- Forecast service
app/services/forecast_service.py - Forecast inference
shelfcash_forecast/pipeline/inference_pipeline.py - Forecast training
shelfcash_forecast/pipeline/training_pipeline.py - Ingredient demand
shelfcash_forecast/pipeline/ingredient_demand_pipeline.py - BOM conversion
shelfcash_forecast/bom/engine.py - Forecast core
shelfcash_core/pipeline
Planning and decisions
- Procurement planning
app/services/procurement_planning_service.py - Decision run
app/services/decision_planning_service.py - Decision package
app/services/decision/build_decision_brief.py - Decision intelligence
app/decision_intelligence - Decision read models
app/services/decision
Persistence and providers
- Application database
app/db/session.py - LLM provider
app/llm/openrouter_qwen.py - Forecast artifacts
shelfcash_forecast/registry
Other components
- Store operator
Connections 22
- Store operator → FastAPI app: sends requests
README.md - FastAPI app → Import routes: routes to
app/main.py - Import routes → Import service: handles imports
- Import service → Sheet ingestion: processes sheets
app/services/import_service.py - Import service → Application database: persists imports
app/services/import_service.py - FastAPI app → Forecast routes: routes to
app/main.py - Forecast routes → Forecast service: runs forecasts
- Forecast service → Forecast inference: requests inference
- Forecast inference → Forecast artifacts: loads artifacts
shelfcash_forecast/pipeline/inference_pipeline.py - Forecast training → Forecast artifacts: writes artifacts
shelfcash_forecast/pipeline/training_pipeline.py - Forecast inference → Ingredient demand: feeds demand
shelfcash_forecast/pipeline/ingredient_demand_pipeline.py - Ingredient demand → BOM conversion: converts forecast
shelfcash_forecast/pipeline/ingredient_demand_pipeline.py - BOM conversion → Procurement planning: provides ingredient demand
- Operational data → Procurement planning: supplies operational data
- Procurement planning → Decision run: plans purchases
- Decision run → Decision package: builds package
- Decision package → Decision intelligence: assembles evidence
- Decision run → Decision read models: serves read models
- Decision read models → Store operator: returns brief or explanation
README.md - Catalog and recipes → BOM conversion: supplies recipes
- Import service → LLM provider: requests mapping help
- Forecast core → Forecast inference: supports forecasting