# mangalamshrivastava61-hash/cyclops architecture

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

- Interactive diagram: https://gitdiagram.com/mangalamshrivastava61-hash/cyclops
- Repository: https://github.com/mangalamshrivastava61-hash/cyclops

## Overview

ORACLE is a retail decision-intelligence application for planners. Its main workflow turns demand and inventory evidence into forecasts and replenishment recommendations, lets planners inspect or stress-test decisions, records their actions, and applies governance through circuit state and earned authority. The graph separates the planner-facing experience, API/domain services, and persisted records. The README documents product capabilities; source-index references and excerpts support backend wiring. Frontend-to-API wiring and some unsampled service internals are not verified, so that connection is dashed.

Main entry points: [`backend/app/main.py`](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/main.py) (API application), [`backend/app/repository.py`](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/repository.py) (Data repository), [`backend/app/services/decisions.py`](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/decisions.py) (Decision actions), [`backend/app/routers/catalog.py`](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/routers/catalog.py) (Catalog routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planner["Planner experience"]
  node_frontend["Planner workspace"]
  node_ask_view["Ask ORACLE<br/>[AskView.tsx]"]
  node_stress_view["Break My Plan<br/>[BreakMyPlan.tsx]"]
  node_ledger_view["Decision ledger<br/>[LedgerView.tsx]"]
end

subgraph group_api["API and domain"]
  node_api_app["API application<br/>[main.py]"]
  node_catalog_api["Catalog routes<br/>[catalog.py]"]
  node_decision_api["Decision routes<br/>[decisions.py]"]
  node_ledger_api["Ledger routes<br/>[ledger.py]"]
  node_simulation_api["Simulation routes<br/>[simulation.py]"]
  node_ask_api["Ask routes<br/>[ask.py]"]
  node_decision_service["Decision actions<br/>[decisions.py]"]
  node_ask_service["Grounded answers<br/>[ask.py]"]
  node_policy["Replenishment policy<br/>[policy.py]"]
  node_scenario["Stress scenarios<br/>[scenarios.py]"]
end

subgraph group_governance["Evidence and governance"]
  node_authority["Earned authority<br/>[authority.py]"]
  node_governance_services["Evidence and state<br/>[state.py]"]
  node_ledger_service["Ledger operations<br/>[ledger.py]"]
  node_presentation["Ledger presentation<br/>[presentation.py]"]
end

subgraph group_storage["Records and forecasting"]
  node_forecast_service["Forecast provider<br/>[forecast.py]"]
  node_ml_forecast["ML forecasting<br/>[ml_forecast.py]"]
  node_repository["Data repository<br/>[repository.py]"]
  node_db_models[("Domain records<br/>[models.py]")]
  node_db_sessions[("Database sessions<br/>[db.py]")]
  node_seed["Demo world seed<br/>[loader.py]"]
end

node_planner_actor(("Retail planner"))

node_planner_actor -->|"uses"| node_frontend
node_frontend -.->|"requests API"| node_api_app
node_api_app -->|"registers routes"| node_catalog_api
node_api_app -->|"registers routes"| node_decision_api
node_api_app -->|"registers routes"| node_ledger_api
node_api_app -->|"registers routes"| node_simulation_api
node_api_app -->|"registers routes"| node_ask_api
node_api_app -->|"creates sessions"| node_db_sessions
node_api_app -->|"seeds on startup"| node_seed
node_api_app -->|"registers provider"| node_forecast_service
node_decision_api -->|"dispatches actions"| node_decision_service
node_decision_service -->|"builds policy input"| node_policy
node_decision_service -->|"appends actions"| node_ledger_service
node_decision_service -->|"loads and saves"| node_repository
node_decision_service -->|"gets forecast"| node_forecast_service
node_ask_api -->|"dispatches questions"| node_ask_service
node_ask_service -->|"reads records"| node_repository
node_ask_service -->|"tests scenarios"| node_policy
node_ask_service -->|"uses authority"| node_authority
node_catalog_api -->|"reads catalog"| node_repository
node_catalog_api -->|"gets authority"| node_authority
node_catalog_api -->|"gets scenarios"| node_scenario
node_ledger_api -->|"reads ledger"| node_ledger_service
node_ledger_api -->|"formats entries"| node_presentation
node_simulation_api -->|"resets ledger"| node_ledger_service
node_simulation_api -->|"resets world"| node_seed
node_simulation_api -->|"reads state"| node_repository
node_authority -->|"reads governance records"| node_repository
node_forecast_service -->|"loads stored forecast"| node_repository
node_api_app -->|"selects provider"| node_ml_forecast
node_repository -->|"queries records"| node_db_models
node_repository -.->|"uses sessions"| node_db_sessions
node_db_models -->|"uses base"| node_db_sessions
node_seed -->|"inserts records"| node_db_models
node_seed -->|"uses database"| node_db_sessions
node_planner_actor -->|"asks questions"| node_ask_view
node_planner_actor -->|"stress-tests plans"| node_stress_view
node_planner_actor -->|"reviews outcomes"| node_ledger_view

click node_frontend "https://github.com/mangalamshrivastava61-hash/cyclops/tree/main/frontend/src/app"
click node_ask_view "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/frontend/src/components/ask/AskView.tsx"
click node_stress_view "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/frontend/src/components/break-my-plan/BreakMyPlan.tsx"
click node_ledger_view "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/frontend/src/components/ledger/LedgerView.tsx"
click node_api_app "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/main.py"
click node_catalog_api "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/routers/catalog.py"
click node_decision_api "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/routers/decisions.py"
click node_ledger_api "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/routers/ledger.py"
click node_simulation_api "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/routers/simulation.py"
click node_ask_api "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/routers/ask.py"
click node_decision_service "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/decisions.py"
click node_ask_service "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/ask.py"
click node_policy "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/policy.py"
click node_scenario "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/scenarios.py"
click node_forecast_service "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/forecast.py"
click node_ml_forecast "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/ml_forecast.py"
click node_authority "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/authority.py"
click node_governance_services "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/state.py"
click node_ledger_service "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/ledger.py"
click node_presentation "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/presentation.py"
click node_repository "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/repository.py"
click node_db_models "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/models.py"
click node_db_sessions "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/db.py"
click node_seed "https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/seed/loader.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_frontend,node_ask_view,node_stress_view,node_ledger_view toneBlue
class node_api_app,node_catalog_api,node_decision_api,node_ledger_api,node_simulation_api,node_ask_api,node_decision_service,node_ask_service,node_policy,node_scenario toneAmber
class node_authority,node_governance_services,node_ledger_service,node_presentation toneMint
class node_forecast_service,node_ml_forecast,node_repository,node_db_models,node_db_sessions,node_seed toneRose
class node_planner_actor toneIndigo
```

## Components

### Planner experience

- [Planner workspace](https://github.com/mangalamshrivastava61-hash/cyclops/tree/main/frontend/src/app): `frontend/src/app`
- [Ask ORACLE](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/frontend/src/components/ask/AskView.tsx): `frontend/src/components/ask/AskView.tsx`
- [Break My Plan](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/frontend/src/components/break-my-plan/BreakMyPlan.tsx): `frontend/src/components/break-my-plan/BreakMyPlan.tsx`
- [Decision ledger](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/frontend/src/components/ledger/LedgerView.tsx): `frontend/src/components/ledger/LedgerView.tsx`

### API and domain

- [API application](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/main.py): `backend/app/main.py`
- [Catalog routes](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/routers/catalog.py): `backend/app/routers/catalog.py`
- [Decision routes](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/routers/decisions.py): `backend/app/routers/decisions.py`
- [Ledger routes](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/routers/ledger.py): `backend/app/routers/ledger.py`
- [Simulation routes](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/routers/simulation.py): `backend/app/routers/simulation.py`
- [Ask routes](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/routers/ask.py): `backend/app/routers/ask.py`
- [Decision actions](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/decisions.py): `backend/app/services/decisions.py`
- [Grounded answers](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/ask.py): `backend/app/services/ask.py`
- [Replenishment policy](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/policy.py): `backend/app/services/policy.py`
- [Stress scenarios](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/scenarios.py): `backend/app/services/scenarios.py`

### Evidence and governance

- [Earned authority](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/authority.py): `backend/app/services/authority.py`
- [Evidence and state](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/state.py): `backend/app/services/state.py`
- [Ledger operations](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/ledger.py): `backend/app/services/ledger.py`
- [Ledger presentation](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/presentation.py): `backend/app/services/presentation.py`

### Records and forecasting

- [Forecast provider](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/forecast.py): `backend/app/services/forecast.py`
- [ML forecasting](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/services/ml_forecast.py): `backend/app/services/ml_forecast.py`
- [Data repository](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/repository.py): `backend/app/repository.py`
- [Domain records](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/models.py): `backend/app/models.py`
- [Database sessions](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/db.py): `backend/app/db.py`
- [Demo world seed](https://github.com/mangalamshrivastava61-hash/cyclops/blob/main/backend/app/seed/loader.py): `backend/app/seed/loader.py`

### Other components

- **Retail planner**

## Connections

- Retail planner → Planner workspace: uses
- Planner workspace → API application: requests API
- API application → Catalog routes: registers routes (evidence: `backend/app/main.py`)
- API application → Decision routes: registers routes (evidence: `backend/app/main.py`)
- API application → Ledger routes: registers routes (evidence: `backend/app/main.py`)
- API application → Simulation routes: registers routes (evidence: `backend/app/main.py`)
- API application → Ask routes: registers routes (evidence: `backend/app/main.py`)
- API application → Database sessions: creates sessions (evidence: `backend/app/main.py`)
- API application → Demo world seed: seeds on startup (evidence: `backend/app/main.py`)
- API application → Forecast provider: registers provider (evidence: `backend/app/main.py`)
- Decision routes → Decision actions: dispatches actions (evidence: `backend/app/routers/decisions.py`)
- Decision actions → Replenishment policy: builds policy input (evidence: `backend/app/services/decisions.py`)
- Decision actions → Ledger operations: appends actions (evidence: `backend/app/services/decisions.py`)
- Decision actions → Data repository: loads and saves (evidence: `backend/app/services/decisions.py`)
- Decision actions → Forecast provider: gets forecast (evidence: `backend/app/services/decisions.py`)
- Ask routes → Grounded answers: dispatches questions (evidence: `backend/app/routers/ask.py`)
- Grounded answers → Data repository: reads records (evidence: `backend/app/services/ask.py`)
- Grounded answers → Replenishment policy: tests scenarios (evidence: `backend/app/services/ask.py`)
- Grounded answers → Earned authority: uses authority (evidence: `backend/app/services/ask.py`)
- Catalog routes → Data repository: reads catalog (evidence: `backend/app/routers/catalog.py`)
- Catalog routes → Earned authority: gets authority (evidence: `backend/app/routers/catalog.py`)
- Catalog routes → Stress scenarios: gets scenarios (evidence: `backend/app/routers/catalog.py`)
- Ledger routes → Ledger operations: reads ledger (evidence: `backend/app/routers/ledger.py`)
- Ledger routes → Ledger presentation: formats entries (evidence: `backend/app/routers/ledger.py`)
- Simulation routes → Ledger operations: resets ledger (evidence: `backend/app/routers/simulation.py`)
- Simulation routes → Demo world seed: resets world (evidence: `backend/app/routers/simulation.py`)
- Simulation routes → Data repository: reads state (evidence: `backend/app/routers/simulation.py`)
- Earned authority → Data repository: reads governance records (evidence: `backend/app/services/authority.py`)
- Forecast provider → Data repository: loads stored forecast (evidence: `backend/app/services/forecast.py`)
- API application → ML forecasting: selects provider (evidence: `backend/app/main.py`)
- Data repository → Domain records: queries records (evidence: `backend/app/repository.py`)
- Data repository → Database sessions: uses sessions
- Domain records → Database sessions: uses base (evidence: `backend/app/models.py`)
- Demo world seed → Domain records: inserts records (evidence: `backend/app/seed/loader.py`)
- Demo world seed → Database sessions: uses database (evidence: `backend/app/seed/loader.py`)
- Retail planner → Ask ORACLE: asks questions
- Retail planner → Break My Plan: stress-tests plans
- Retail planner → Decision ledger: reviews outcomes
