# trankhanhnamhoccode/shelfcash_backend architecture

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

- Interactive diagram: https://gitdiagram.com/trankhanhnamhoccode/shelfcash_backend
- Repository: https://github.com/trankhanhnamhoccode/shelfcash_backend

## Overview

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: [`app/services/import_service.py`](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/services/import_service.py) (Import service), [`shelfcash_forecast/pipeline/inference_pipeline.py`](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/shelfcash_forecast/pipeline/inference_pipeline.py) (Forecast inference), [`app/main.py`](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/main.py) (FastAPI app), [`app/services/decision_planning_service.py`](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/services/decision_planning_service.py) (Decision run)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and imports"]
  node_http_api["FastAPI app<br/>[main.py]"]
  node_import_api["Import routes<br/>[imports.py]"]
  node_import_service["Import service<br/>[import_service.py]"]
  node_ingestion["Sheet ingestion"]
  node_forecast_api["Forecast routes<br/>[forecast.py]"]
end

subgraph group_domain["Store operations"]
  node_catalog["Catalog and recipes<br/>[catalog_service.py]"]
  node_operations["Operational data"]
end

subgraph group_forecast["Forecast and demand"]
  node_forecast_service["Forecast service"]
  node_inference["Forecast inference"]
  node_forecast_training["Forecast training"]
  node_ingredient_demand["Ingredient demand"]
  node_bom["BOM conversion<br/>[engine.py]"]
  node_forecast_core["Forecast core"]
end

subgraph group_planning["Planning and decisions"]
  node_procurement["Procurement planning"]
  node_decision_run["Decision run"]
  node_decision_build["Decision package"]
  node_decision_intel["Decision intelligence"]
  node_decision_reads["Decision read models"]
end

subgraph group_data["Persistence and providers"]
  node_db[("Application database<br/>[session.py]")]
  node_llm_provider["LLM provider<br/>[openrouter_qwen.py]"]
  node_forecast_store[("Forecast artifacts")]
end

node_operator(("Store operator"))

node_operator -->|"sends requests"| node_http_api
node_http_api -->|"routes to"| node_import_api
node_import_api -.->|"handles imports"| node_import_service
node_import_service -->|"processes sheets"| node_ingestion
node_import_service -->|"persists imports"| node_db
node_http_api -->|"routes to"| node_forecast_api
node_forecast_api -.->|"runs forecasts"| node_forecast_service
node_forecast_service -.->|"requests inference"| node_inference
node_inference -->|"loads artifacts"| node_forecast_store
node_forecast_training -.->|"writes artifacts"| node_forecast_store
node_inference -.->|"feeds demand"| node_ingredient_demand
node_ingredient_demand -->|"converts forecast"| node_bom
node_bom -.->|"provides ingredient demand"| node_procurement
node_operations -.->|"supplies operational data"| node_procurement
node_procurement -.->|"plans purchases"| node_decision_run
node_decision_run -.->|"builds package"| node_decision_build
node_decision_build -.->|"assembles evidence"| node_decision_intel
node_decision_run -.->|"serves read models"| node_decision_reads
node_decision_reads -->|"returns brief or explanation"| node_operator
node_catalog -.->|"supplies recipes"| node_bom
node_import_service -.->|"requests mapping help"| node_llm_provider
node_forecast_core -.->|"supports forecasting"| node_inference

click node_http_api "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/main.py"
click node_import_api "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/api/imports.py"
click node_import_service "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/services/import_service.py"
click node_ingestion "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/core/ingestion_pipeline.py"
click node_catalog "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/services/catalog_service.py"
click node_operations "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/services/operational_service.py"
click node_forecast_api "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/api/forecast.py"
click node_forecast_service "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/services/forecast_service.py"
click node_inference "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/shelfcash_forecast/pipeline/inference_pipeline.py"
click node_forecast_training "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/shelfcash_forecast/pipeline/training_pipeline.py"
click node_ingredient_demand "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/shelfcash_forecast/pipeline/ingredient_demand_pipeline.py"
click node_bom "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/shelfcash_forecast/bom/engine.py"
click node_procurement "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/services/procurement_planning_service.py"
click node_decision_run "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/services/decision_planning_service.py"
click node_decision_build "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/services/decision/build_decision_brief.py"
click node_decision_intel "https://github.com/trankhanhnamhoccode/shelfcash_backend/tree/main/app/decision_intelligence"
click node_decision_reads "https://github.com/trankhanhnamhoccode/shelfcash_backend/tree/main/app/services/decision"
click node_db "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/db/session.py"
click node_llm_provider "https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/llm/openrouter_qwen.py"
click node_forecast_core "https://github.com/trankhanhnamhoccode/shelfcash_backend/tree/main/shelfcash_core/pipeline"
click node_forecast_store "https://github.com/trankhanhnamhoccode/shelfcash_backend/tree/main/shelfcash_forecast/registry"

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_http_api,node_import_api,node_import_service,node_ingestion,node_forecast_api toneBlue
class node_catalog,node_operations toneAmber
class node_forecast_service,node_inference,node_forecast_training,node_ingredient_demand,node_bom,node_forecast_core toneMint
class node_procurement,node_decision_run,node_decision_build,node_decision_intel,node_decision_reads toneRose
class node_db,node_llm_provider,node_forecast_store,node_operator toneIndigo
```

## Components

### API and imports

- [FastAPI app](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/main.py): `app/main.py`
- [Import routes](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/api/imports.py): `app/api/imports.py`
- [Import service](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/services/import_service.py): `app/services/import_service.py`
- [Sheet ingestion](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/core/ingestion_pipeline.py): `app/core/ingestion_pipeline.py`
- [Forecast routes](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/api/forecast.py): `app/api/forecast.py`

### Store operations

- [Catalog and recipes](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/services/catalog_service.py): `app/services/catalog_service.py`
- [Operational data](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/services/operational_service.py): `app/services/operational_service.py`

### Forecast and demand

- [Forecast service](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/services/forecast_service.py): `app/services/forecast_service.py`
- [Forecast inference](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/shelfcash_forecast/pipeline/inference_pipeline.py): `shelfcash_forecast/pipeline/inference_pipeline.py`
- [Forecast training](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/shelfcash_forecast/pipeline/training_pipeline.py): `shelfcash_forecast/pipeline/training_pipeline.py`
- [Ingredient demand](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/shelfcash_forecast/pipeline/ingredient_demand_pipeline.py): `shelfcash_forecast/pipeline/ingredient_demand_pipeline.py`
- [BOM conversion](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/shelfcash_forecast/bom/engine.py): `shelfcash_forecast/bom/engine.py`
- [Forecast core](https://github.com/trankhanhnamhoccode/shelfcash_backend/tree/main/shelfcash_core/pipeline): `shelfcash_core/pipeline`

### Planning and decisions

- [Procurement planning](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/services/procurement_planning_service.py): `app/services/procurement_planning_service.py`
- [Decision run](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/services/decision_planning_service.py): `app/services/decision_planning_service.py`
- [Decision package](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/services/decision/build_decision_brief.py): `app/services/decision/build_decision_brief.py`
- [Decision intelligence](https://github.com/trankhanhnamhoccode/shelfcash_backend/tree/main/app/decision_intelligence): `app/decision_intelligence`
- [Decision read models](https://github.com/trankhanhnamhoccode/shelfcash_backend/tree/main/app/services/decision): `app/services/decision`

### Persistence and providers

- [Application database](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/db/session.py): `app/db/session.py`
- [LLM provider](https://github.com/trankhanhnamhoccode/shelfcash_backend/blob/main/app/llm/openrouter_qwen.py): `app/llm/openrouter_qwen.py`
- [Forecast artifacts](https://github.com/trankhanhnamhoccode/shelfcash_backend/tree/main/shelfcash_forecast/registry): `shelfcash_forecast/registry`

### Other components

- **Store operator**

## Connections

- Store operator → FastAPI app: sends requests (evidence: `README.md`)
- FastAPI app → Import routes: routes to (evidence: `app/main.py`)
- Import routes → Import service: handles imports
- Import service → Sheet ingestion: processes sheets (evidence: `app/services/import_service.py`)
- Import service → Application database: persists imports (evidence: `app/services/import_service.py`)
- FastAPI app → Forecast routes: routes to (evidence: `app/main.py`)
- Forecast routes → Forecast service: runs forecasts
- Forecast service → Forecast inference: requests inference
- Forecast inference → Forecast artifacts: loads artifacts (evidence: `shelfcash_forecast/pipeline/inference_pipeline.py`)
- Forecast training → Forecast artifacts: writes artifacts (evidence: `shelfcash_forecast/pipeline/training_pipeline.py`)
- Forecast inference → Ingredient demand: feeds demand (evidence: `shelfcash_forecast/pipeline/ingredient_demand_pipeline.py`)
- Ingredient demand → BOM conversion: converts forecast (evidence: `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 (evidence: `README.md`)
- Catalog and recipes → BOM conversion: supplies recipes
- Import service → LLM provider: requests mapping help
- Forecast core → Forecast inference: supports forecasting
