# rmsofficialsyt/citimart3 architecture

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

- Interactive diagram: https://gitdiagram.com/rmsofficialsyt/citimart3
- Repository: https://github.com/rmsofficialsyt/citimart3

## Overview

CITIMART Daily Operations is a multi-store retail operations portal for live KPI pacing, manual sales and footfall logging, store governance, inventory workflows, and reporting. Store staff and administrators use the frontend; the backend authenticates and scopes operations, serves domain APIs, and reads or writes MongoDB-backed operational data. The graph includes the documented AI copilot, directives, requisitions, stock and staff management, and report exports. Some relationships rely on the README or SOURCE INDEX; unsampled implementation links are omitted or marked unverified.

Main entry points: [`frontend/src/App.tsx`](https://github.com/rmsofficialsyt/citimart3/blob/main/frontend/src/App.tsx) (Operations portal), [`backend/api/routes_daily.py`](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/api/routes_daily.py) (Daily operations API), [`backend/src/daily_dashboard_store.py`](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/daily_dashboard_store.py) (Daily data and KPIs), [`backend/app.py`](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/app.py) (API application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Staff experience"]
  node_frontend["Operations portal<br/>[App.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_login["Login experience<br/>[LoginPage.tsx]"]
  node_daily_ui["Daily dashboard"]
  node_history_ui["Operations history<br/>[HistoryPage.tsx]"]
  node_requisition_ui["Requisition entry"]
end

subgraph group_access["Identity and access"]
  node_auth_routes["Authentication API<br/>[routes_auth.py]"]
  node_auth_rules["JWT authorization<br/>[auth.py]"]
  node_users["User accounts<br/>[user_store.py]"]
  node_sessions["Session store<br/>[session_store.py]"]
end

subgraph group_operations["Daily operations"]
  node_daily_routes["Daily operations API<br/>[routes_daily.py]"]
  node_daily_store["Daily data and KPIs"]
  node_kpi_engine["KPI calculations<br/>[kpi_engine.py]"]
  node_target_engine["Target adjustment"]
  node_charts["Pacing charts<br/>[charts.py]"]
end

subgraph group_governance["Store governance"]
  node_directives["Executive directives"]
  node_requisitions["Product requisitions"]
  node_staff_stock["Staff and stock APIs<br/>[routes_stocks.py]"]
  node_copilot["AI operations copilot<br/>[routes_chat.py]"]
end

subgraph group_platform["Data and reporting"]
  node_app["API application<br/>[app.py]"]
  node_mongo[("MongoDB<br/>[engine.py]")]
  node_collections[("Operational collections<br/>[models.py]")]
  node_redis[("Redis client<br/>[redis_client.py]")]
  node_reporting["Report generation<br/>[daily_report.py]"]
  node_queue["Background jobs<br/>[bullmq_client.py]"]
end

node_staff(("Store staff"))

node_staff -->|"uses"| node_frontend
node_frontend -.->|"presents"| node_login
node_frontend -.->|"presents"| node_daily_ui
node_frontend -.->|"presents"| node_history_ui
node_frontend -.->|"presents"| node_requisition_ui
node_frontend -.->|"uses"| node_api_client
node_api_client -.->|"calls"| node_app
node_app -->|"registers"| node_auth_routes
node_app -->|"registers"| node_daily_routes
node_app -->|"registers"| node_directives
node_app -->|"registers"| node_staff_stock
node_auth_routes -->|"uses"| node_auth_rules
node_auth_routes -->|"reads"| node_users
node_auth_routes -->|"uses"| node_sessions
node_auth_rules -->|"checks"| node_sessions
node_daily_routes -->|"authorizes"| node_auth_rules
node_daily_routes -->|"requests KPIs"| node_daily_store
node_daily_routes -->|"uses"| node_charts
node_daily_store -->|"uses"| node_kpi_engine
node_daily_store -->|"uses"| node_target_engine
node_daily_store -->|"reads and writes"| node_collections
node_collections -.->|"stored in"| node_mongo
node_directives -.->|"authorizes"| node_auth_rules
node_requisitions -->|"stores records"| node_collections
node_staff_stock -.->|"authorizes"| node_auth_rules
node_staff_stock -.->|"uses"| node_collections
node_copilot -->|"gets live KPIs"| node_daily_store
node_copilot -.->|"uses directive context"| node_directives
node_daily_routes -->|"uses reports"| node_reporting
node_daily_routes -.->|"enqueues jobs"| node_queue
node_queue -.->|"connects"| node_redis
node_daily_store -->|"uses cache"| node_redis

click node_frontend "https://github.com/rmsofficialsyt/citimart3/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/rmsofficialsyt/citimart3/blob/main/frontend/src/api/client.ts"
click node_login "https://github.com/rmsofficialsyt/citimart3/blob/main/frontend/src/pages/LoginPage.tsx"
click node_daily_ui "https://github.com/rmsofficialsyt/citimart3/blob/main/frontend/src/pages/StoreDailyDashboard.tsx"
click node_history_ui "https://github.com/rmsofficialsyt/citimart3/blob/main/frontend/src/pages/HistoryPage.tsx"
click node_requisition_ui "https://github.com/rmsofficialsyt/citimart3/blob/main/frontend/src/pages/ProductRequisitionPage.tsx"
click node_auth_routes "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/api/routes_auth.py"
click node_auth_rules "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/api/auth.py"
click node_users "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/user_store.py"
click node_sessions "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/session_store.py"
click node_daily_routes "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/api/routes_daily.py"
click node_daily_store "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/daily_dashboard_store.py"
click node_kpi_engine "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/kpi_engine.py"
click node_target_engine "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/target_adjustment_engine.py"
click node_charts "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/charts.py"
click node_directives "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/api/routes_directives.py"
click node_requisitions "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/requisitions_store.py"
click node_staff_stock "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/api/routes_stocks.py"
click node_copilot "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/api/routes_chat.py"
click node_app "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/app.py"
click node_mongo "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/db/engine.py"
click node_collections "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/db/models.py"
click node_redis "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/db/redis_client.py"
click node_reporting "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/daily_report.py"
click node_queue "https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/queue/bullmq_client.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_api_client,node_login,node_daily_ui,node_history_ui,node_requisition_ui toneBlue
class node_auth_routes,node_auth_rules,node_users,node_sessions toneAmber
class node_daily_routes,node_daily_store,node_kpi_engine,node_target_engine,node_charts toneMint
class node_directives,node_requisitions,node_staff_stock,node_copilot toneRose
class node_app,node_mongo,node_collections,node_redis,node_reporting,node_queue,node_staff toneIndigo
```

## Components

### Staff experience

- [Operations portal](https://github.com/rmsofficialsyt/citimart3/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/rmsofficialsyt/citimart3/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Login experience](https://github.com/rmsofficialsyt/citimart3/blob/main/frontend/src/pages/LoginPage.tsx): `frontend/src/pages/LoginPage.tsx`
- [Daily dashboard](https://github.com/rmsofficialsyt/citimart3/blob/main/frontend/src/pages/StoreDailyDashboard.tsx): `frontend/src/pages/StoreDailyDashboard.tsx`
- [Operations history](https://github.com/rmsofficialsyt/citimart3/blob/main/frontend/src/pages/HistoryPage.tsx): `frontend/src/pages/HistoryPage.tsx`
- [Requisition entry](https://github.com/rmsofficialsyt/citimart3/blob/main/frontend/src/pages/ProductRequisitionPage.tsx): `frontend/src/pages/ProductRequisitionPage.tsx`

### Identity and access

- [Authentication API](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/api/routes_auth.py): `backend/api/routes_auth.py`
- [JWT authorization](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/api/auth.py): `backend/api/auth.py`
- [User accounts](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/user_store.py): `backend/src/user_store.py`
- [Session store](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/session_store.py): `backend/src/session_store.py`

### Daily operations

- [Daily operations API](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/api/routes_daily.py): `backend/api/routes_daily.py`
- [Daily data and KPIs](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/daily_dashboard_store.py): `backend/src/daily_dashboard_store.py`
- [KPI calculations](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/kpi_engine.py): `backend/src/kpi_engine.py`
- [Target adjustment](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/target_adjustment_engine.py): `backend/src/target_adjustment_engine.py`
- [Pacing charts](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/charts.py): `backend/src/charts.py`

### Store governance

- [Executive directives](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/api/routes_directives.py): `backend/api/routes_directives.py`
- [Product requisitions](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/requisitions_store.py): `backend/src/requisitions_store.py`
- [Staff and stock APIs](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/api/routes_stocks.py): `backend/api/routes_stocks.py`
- [AI operations copilot](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/api/routes_chat.py): `backend/api/routes_chat.py`

### Data and reporting

- [API application](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/app.py): `backend/app.py`
- [MongoDB](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/db/engine.py): `backend/db/engine.py`
- [Operational collections](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/db/models.py): `backend/db/models.py`
- [Redis client](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/db/redis_client.py): `backend/db/redis_client.py`
- [Report generation](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/daily_report.py): `backend/src/daily_report.py`
- [Background jobs](https://github.com/rmsofficialsyt/citimart3/blob/main/backend/src/queue/bullmq_client.py): `backend/src/queue/bullmq_client.py`

### Other components

- **Store staff**

## Connections

- Store staff → Operations portal: uses (evidence: `README.md`)
- Operations portal → Login experience: presents
- Operations portal → Daily dashboard: presents
- Operations portal → Operations history: presents
- Operations portal → Requisition entry: presents
- Operations portal → API client: uses
- API client → API application: calls
- API application → Authentication API: registers (evidence: `backend/app.py`)
- API application → Daily operations API: registers (evidence: `backend/app.py`)
- API application → Executive directives: registers (evidence: `backend/app.py`)
- API application → Staff and stock APIs: registers (evidence: `backend/app.py`)
- Authentication API → JWT authorization: uses (evidence: `backend/api/routes_auth.py`)
- Authentication API → User accounts: reads (evidence: `backend/api/routes_auth.py`)
- Authentication API → Session store: uses (evidence: `backend/api/routes_auth.py`)
- JWT authorization → Session store: checks (evidence: `backend/api/auth.py`)
- Daily operations API → JWT authorization: authorizes (evidence: `backend/api/routes_daily.py`)
- Daily operations API → Daily data and KPIs: requests KPIs (evidence: `backend/api/routes_daily.py`)
- Daily operations API → Pacing charts: uses (evidence: `backend/api/routes_daily.py`)
- Daily data and KPIs → KPI calculations: uses (evidence: `backend/src/daily_dashboard_store.py`)
- Daily data and KPIs → Target adjustment: uses (evidence: `backend/src/daily_dashboard_store.py`)
- Daily data and KPIs → Operational collections: reads and writes (evidence: `backend/src/daily_dashboard_store.py`)
- Operational collections → MongoDB: stored in
- Executive directives → JWT authorization: authorizes
- Product requisitions → Operational collections: stores records (evidence: `backend/src/requisitions_store.py`)
- Staff and stock APIs → JWT authorization: authorizes (evidence: `backend/api/routes_stocks.py`)
- Staff and stock APIs → Operational collections: uses
- AI operations copilot → Daily data and KPIs: gets live KPIs (evidence: `backend/api/routes_chat.py`)
- AI operations copilot → Executive directives: uses directive context
- Daily operations API → Report generation: uses reports (evidence: `backend/api/routes_daily.py`)
- Daily operations API → Background jobs: enqueues jobs
- Background jobs → Redis client: connects
- Daily data and KPIs → Redis client: uses cache (evidence: `backend/src/daily_dashboard_store.py`)