How mangalamshrivastava61-hash/cyclops works
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: main.py API application · repository.py Data repository · decisions.py Decision actions · catalog.py Catalog routes
Components 25
Planner experience
- Planner workspace
frontend/src/app - Ask ORACLE
frontend/src/components/ask/AskView.tsx - Break My Plan
frontend/src/components/break-my-plan/BreakMyPlan.tsx - Decision ledger
frontend/src/components/ledger/LedgerView.tsx
API and domain
- API application
backend/app/main.py - Catalog routes
backend/app/routers/catalog.py - Decision routes
backend/app/routers/decisions.py - Ledger routes
backend/app/routers/ledger.py - Simulation routes
backend/app/routers/simulation.py - Ask routes
backend/app/routers/ask.py - Decision actions
backend/app/services/decisions.py - Grounded answers
backend/app/services/ask.py - Replenishment policy
backend/app/services/policy.py - Stress scenarios
backend/app/services/scenarios.py
Evidence and governance
- Earned authority
backend/app/services/authority.py - Evidence and state
backend/app/services/state.py - Ledger operations
backend/app/services/ledger.py - Ledger presentation
backend/app/services/presentation.py
Records and forecasting
- Forecast provider
backend/app/services/forecast.py - ML forecasting
backend/app/services/ml_forecast.py - Data repository
backend/app/repository.py - Domain records
backend/app/models.py - Database sessions
backend/app/db.py - Demo world seed
backend/app/seed/loader.py
Other components
- Retail planner
Connections 38
- Retail planner → Planner workspace: uses
- Planner workspace → API application: requests API
- API application → Catalog routes: registers routes
backend/app/main.py - API application → Decision routes: registers routes
backend/app/main.py - API application → Ledger routes: registers routes
backend/app/main.py - API application → Simulation routes: registers routes
backend/app/main.py - API application → Ask routes: registers routes
backend/app/main.py - API application → Database sessions: creates sessions
backend/app/main.py - API application → Demo world seed: seeds on startup
backend/app/main.py - API application → Forecast provider: registers provider
backend/app/main.py - Decision routes → Decision actions: dispatches actions
backend/app/routers/decisions.py - Decision actions → Replenishment policy: builds policy input
backend/app/services/decisions.py - Decision actions → Ledger operations: appends actions
backend/app/services/decisions.py - Decision actions → Data repository: loads and saves
backend/app/services/decisions.py - Decision actions → Forecast provider: gets forecast
backend/app/services/decisions.py - Ask routes → Grounded answers: dispatches questions
backend/app/routers/ask.py - Grounded answers → Data repository: reads records
backend/app/services/ask.py - Grounded answers → Replenishment policy: tests scenarios
backend/app/services/ask.py - Grounded answers → Earned authority: uses authority
backend/app/services/ask.py - Catalog routes → Data repository: reads catalog
backend/app/routers/catalog.py - Catalog routes → Earned authority: gets authority
backend/app/routers/catalog.py - Catalog routes → Stress scenarios: gets scenarios
backend/app/routers/catalog.py - Ledger routes → Ledger operations: reads ledger
backend/app/routers/ledger.py - Ledger routes → Ledger presentation: formats entries
backend/app/routers/ledger.py - Simulation routes → Ledger operations: resets ledger
backend/app/routers/simulation.py - Simulation routes → Demo world seed: resets world
backend/app/routers/simulation.py - Simulation routes → Data repository: reads state
backend/app/routers/simulation.py - Earned authority → Data repository: reads governance records
backend/app/services/authority.py - Forecast provider → Data repository: loads stored forecast
backend/app/services/forecast.py - API application → ML forecasting: selects provider
backend/app/main.py - Data repository → Domain records: queries records
backend/app/repository.py - Data repository → Database sessions: uses sessions
- Domain records → Database sessions: uses base
backend/app/models.py - Demo world seed → Domain records: inserts records
backend/app/seed/loader.py - Demo world seed → Database sessions: uses database
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