# chaitanya697/gridrelief architecture

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

- Interactive diagram: https://gitdiagram.com/chaitanya697/gridrelief
- Repository: https://github.com/chaitanya697/gridrelief

## Overview

GridRelief coordinates resource requests across independent relief centers: requests are accepted, queued, ranked against shareable inventory, then presented for supplier approval, partial approval, or rejection. A dashboard provides the operator workflow, live events, queue health, and optional service controls. The sampled service code establishes the event and HTTP relationships shown; README documentation supplies the dashboard UI capabilities. Inventory, requests, and allocation state are in memory, and approvals do not deduct center stock.

Main entry points: [`dashboard/main.py`](https://github.com/chaitanya697/gridrelief/blob/main/dashboard/main.py) (Dashboard Gateway), [`allocation-service/main.py`](https://github.com/chaitanya697/gridrelief/blob/main/allocation-service/main.py) (Priority Ranking), [`request-service/main.py`](https://github.com/chaitanya697/gridrelief/blob/main/request-service/main.py) (Request Intake), [`center-service/main.py`](https://github.com/chaitanya697/gridrelief/blob/main/center-service/main.py) (Center Management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_coordination["Request Coordination"]
  node_request_api["Request Intake<br/>[main.py]"]
  node_request_state[("Request Records<br/>[main.py]")]
  node_center_api["Center Management<br/>[main.py]"]
  node_inventory_state[("Center Inventory<br/>[main.py]")]
  node_inventory_discovery["Stock Discovery<br/>[main.py]"]
end

subgraph group_allocation["Allocation Decisions"]
  node_allocation_consumer["Request Consumer<br/>[main.py]"]
  node_allocation_state[("Allocation State<br/>[main.py]")]
  node_priority_engine["Priority Ranking<br/>[main.py]"]
  node_recommendations["Supplier Recommendations<br/>[main.py]"]
  node_decision_handler["Supplier Decisions<br/>[main.py]"]
end

subgraph group_operations["Operator Dashboard"]
  node_dashboard_ui["Web Console<br/>[index.html]"]
  node_dashboard_api["Dashboard Gateway<br/>[main.py]"]
  node_live_events["Live Event Stream<br/>[main.py]"]
  node_queue_monitor["Queue Monitor<br/>[main.py]"]
  node_service_controls["Service Controls<br/>[main.py]"]
end

subgraph group_infrastructure["Messaging and Services"]
  node_event_broker["RabbitMQ Broker"]
  node_docker_engine["Docker Engine"]
end

node_operator(("Relief Operator"))

node_operator -->|"uses console"| node_dashboard_ui
node_dashboard_ui -->|"calls API"| node_dashboard_api
node_dashboard_api -->|"forwards requests"| node_request_api
node_dashboard_api -->|"forwards center changes"| node_center_api
node_dashboard_api -->|"forwards decisions"| node_decision_handler
node_dashboard_api -->|"fetches requests"| node_request_api
node_dashboard_api -->|"fetches centers"| node_center_api
node_dashboard_api -->|"fetches recommendations"| node_recommendations
node_request_api -->|"records request"| node_request_state
node_request_api -->|"publishes request.created"| node_event_broker
node_center_api -->|"updates inventory"| node_inventory_state
node_center_api -->|"publishes inventory.updated"| node_event_broker
node_allocation_consumer -->|"consumes request.created"| node_event_broker
node_allocation_consumer -->|"records requests"| node_allocation_state
node_allocation_consumer -->|"triggers recompute"| node_priority_engine
node_priority_engine -->|"fetches shareable stock"| node_inventory_discovery
node_priority_engine -->|"ranks pending requests"| node_allocation_state
node_priority_engine -->|"updates recommendations"| node_recommendations
node_recommendations -->|"publishes allocation.recommended"| node_event_broker
node_decision_handler -->|"records decision"| node_allocation_state
node_decision_handler -->|"publishes approval or rejection"| node_event_broker
node_dashboard_api -->|"serves event stream"| node_live_events
node_live_events -->|"listens to events"| node_event_broker
node_dashboard_api -->|"serves queue health"| node_queue_monitor
node_queue_monitor -->|"reads queue depth"| node_event_broker
node_dashboard_api -->|"routes controls"| node_service_controls
node_service_controls -->|"starts or stops containers"| node_docker_engine
node_dashboard_api -->|"purges queue on reset"| node_event_broker
node_service_controls -.->|"reports control status"| node_operator

click node_dashboard_ui "https://github.com/chaitanya697/gridrelief/blob/main/dashboard/index.html"
click node_dashboard_api "https://github.com/chaitanya697/gridrelief/blob/main/dashboard/main.py"
click node_live_events "https://github.com/chaitanya697/gridrelief/blob/main/dashboard/main.py"
click node_queue_monitor "https://github.com/chaitanya697/gridrelief/blob/main/dashboard/main.py"
click node_service_controls "https://github.com/chaitanya697/gridrelief/blob/main/dashboard/main.py"
click node_request_api "https://github.com/chaitanya697/gridrelief/blob/main/request-service/main.py"
click node_request_state "https://github.com/chaitanya697/gridrelief/blob/main/request-service/main.py"
click node_center_api "https://github.com/chaitanya697/gridrelief/blob/main/center-service/main.py"
click node_inventory_state "https://github.com/chaitanya697/gridrelief/blob/main/center-service/main.py"
click node_inventory_discovery "https://github.com/chaitanya697/gridrelief/blob/main/center-service/main.py"
click node_allocation_consumer "https://github.com/chaitanya697/gridrelief/blob/main/allocation-service/main.py"
click node_allocation_state "https://github.com/chaitanya697/gridrelief/blob/main/allocation-service/main.py"
click node_priority_engine "https://github.com/chaitanya697/gridrelief/blob/main/allocation-service/main.py"
click node_recommendations "https://github.com/chaitanya697/gridrelief/blob/main/allocation-service/main.py"
click node_decision_handler "https://github.com/chaitanya697/gridrelief/blob/main/allocation-service/main.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_request_api,node_request_state,node_center_api,node_inventory_state,node_inventory_discovery toneBlue
class node_allocation_consumer,node_allocation_state,node_priority_engine,node_recommendations,node_decision_handler toneAmber
class node_dashboard_ui,node_dashboard_api,node_live_events,node_queue_monitor,node_service_controls toneMint
class node_event_broker,node_docker_engine toneRose
class node_operator toneIndigo
```

## Components

### Request Coordination

- [Request Intake](https://github.com/chaitanya697/gridrelief/blob/main/request-service/main.py): `request-service/main.py`
- [Request Records](https://github.com/chaitanya697/gridrelief/blob/main/request-service/main.py): `request-service/main.py`
- [Center Management](https://github.com/chaitanya697/gridrelief/blob/main/center-service/main.py): `center-service/main.py`
- [Center Inventory](https://github.com/chaitanya697/gridrelief/blob/main/center-service/main.py): `center-service/main.py`
- [Stock Discovery](https://github.com/chaitanya697/gridrelief/blob/main/center-service/main.py): `center-service/main.py`

### Allocation Decisions

- [Request Consumer](https://github.com/chaitanya697/gridrelief/blob/main/allocation-service/main.py): `allocation-service/main.py`
- [Allocation State](https://github.com/chaitanya697/gridrelief/blob/main/allocation-service/main.py): `allocation-service/main.py`
- [Priority Ranking](https://github.com/chaitanya697/gridrelief/blob/main/allocation-service/main.py): `allocation-service/main.py`
- [Supplier Recommendations](https://github.com/chaitanya697/gridrelief/blob/main/allocation-service/main.py): `allocation-service/main.py`
- [Supplier Decisions](https://github.com/chaitanya697/gridrelief/blob/main/allocation-service/main.py): `allocation-service/main.py`

### Operator Dashboard

- [Web Console](https://github.com/chaitanya697/gridrelief/blob/main/dashboard/index.html): `dashboard/index.html`
- [Dashboard Gateway](https://github.com/chaitanya697/gridrelief/blob/main/dashboard/main.py): `dashboard/main.py`
- [Live Event Stream](https://github.com/chaitanya697/gridrelief/blob/main/dashboard/main.py): `dashboard/main.py`
- [Queue Monitor](https://github.com/chaitanya697/gridrelief/blob/main/dashboard/main.py): `dashboard/main.py`
- [Service Controls](https://github.com/chaitanya697/gridrelief/blob/main/dashboard/main.py): `dashboard/main.py`

### Messaging and Services

- **RabbitMQ Broker**
- **Docker Engine**

### Other components

- **Relief Operator**

## Connections

- Relief Operator → Web Console: uses console (evidence: `README.md`)
- Web Console → Dashboard Gateway: calls API (evidence: `README.md`)
- Dashboard Gateway → Request Intake: forwards requests (evidence: `dashboard/main.py`)
- Dashboard Gateway → Center Management: forwards center changes (evidence: `dashboard/main.py`)
- Dashboard Gateway → Supplier Decisions: forwards decisions (evidence: `dashboard/main.py`)
- Dashboard Gateway → Request Intake: fetches requests (evidence: `dashboard/main.py`)
- Dashboard Gateway → Center Management: fetches centers (evidence: `dashboard/main.py`)
- Dashboard Gateway → Supplier Recommendations: fetches recommendations (evidence: `dashboard/main.py`)
- Request Intake → Request Records: records request (evidence: `request-service/main.py`)
- Request Intake → RabbitMQ Broker: publishes request.created (evidence: `request-service/main.py`)
- Center Management → Center Inventory: updates inventory (evidence: `center-service/main.py`)
- Center Management → RabbitMQ Broker: publishes inventory.updated (evidence: `center-service/main.py`)
- Request Consumer → RabbitMQ Broker: consumes request.created (evidence: `allocation-service/main.py`)
- Request Consumer → Allocation State: records requests (evidence: `allocation-service/main.py`)
- Request Consumer → Priority Ranking: triggers recompute (evidence: `allocation-service/main.py`)
- Priority Ranking → Stock Discovery: fetches shareable stock (evidence: `allocation-service/main.py`)
- Priority Ranking → Allocation State: ranks pending requests (evidence: `allocation-service/main.py`)
- Priority Ranking → Supplier Recommendations: updates recommendations (evidence: `allocation-service/main.py`)
- Supplier Recommendations → RabbitMQ Broker: publishes allocation.recommended (evidence: `allocation-service/main.py`)
- Supplier Decisions → Allocation State: records decision (evidence: `allocation-service/main.py`)
- Supplier Decisions → RabbitMQ Broker: publishes approval or rejection (evidence: `allocation-service/main.py`)
- Dashboard Gateway → Live Event Stream: serves event stream (evidence: `dashboard/main.py`)
- Live Event Stream → RabbitMQ Broker: listens to events (evidence: `dashboard/main.py`)
- Dashboard Gateway → Queue Monitor: serves queue health (evidence: `dashboard/main.py`)
- Queue Monitor → RabbitMQ Broker: reads queue depth (evidence: `dashboard/main.py`)
- Dashboard Gateway → Service Controls: routes controls (evidence: `dashboard/main.py`)
- Service Controls → Docker Engine: starts or stops containers (evidence: `dashboard/main.py`)
- Dashboard Gateway → RabbitMQ Broker: purges queue on reset (evidence: `dashboard/main.py`)
- Service Controls → Relief Operator: reports control status
