# prachit27/gridmindai architecture

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

- Interactive diagram: https://gitdiagram.com/prachit27/gridmindai
- Repository: https://github.com/prachit27/gridmindai

## Overview

GridMind accepts a workload through its public dashboard or negotiation API, then coordinates four independent specialists. Their verdicts are checked for joint physical consistency; if they conflict, the orchestrator sends peer positions for another bounded round and returns an auditable decision or escalation. Specialists use a shared harness to assemble scoped facility data, external signals, and policy context, then validate model verdicts with domain guardrails. The README documents memory precedents, decision history, PDF reports, and isolated domain databases. Some subsystem wiring is based on README documentation because its source was not sampled.

Main entry points: [`agents/orchestrator/orchestrator.py`](https://github.com/prachit27/gridmindai/blob/main/agents/orchestrator/orchestrator.py) (Negotiation Loop), [`agents/common/harness.py`](https://github.com/prachit27/gridmindai/blob/main/agents/common/harness.py) (Shared Agent Harness), [`agents/gateway/main.py`](https://github.com/prachit27/gridmindai/blob/main/agents/gateway/main.py) (Agent Gateway), [`agents/web/main.py`](https://github.com/prachit27/gridmindai/blob/main/agents/web/main.py) (Web API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry"]
  node_dashboard["Dashboard<br/>[main.py]"]
  node_web_api["Web API<br/>[main.py]"]
end

subgraph group_negotiation["Negotiation"]
  node_orchestrator_api["Negotiation API<br/>[main.py]"]
  node_orchestrator["Negotiation Loop<br/>[orchestrator.py]"]
  node_consistency["Consistency Check<br/>[consistency.py]"]
  node_decision["Decision and Escalation<br/>[decision.py]"]
  node_report["Decision Report<br/>[report.py]"]
  node_gateway["Agent Gateway<br/>[main.py]"]
end

subgraph group_specialists["Specialists"]
  node_power["Power Specialist<br/>[agent.py]"]
  node_cooling["Cooling Specialist<br/>[agent.py]"]
  node_facilities["Facilities Specialist<br/>[agent.py]"]
  node_cost["Cost Specialist<br/>[agent.py]"]
end

subgraph group_harness["Agent Harness"]
  node_harness["Shared Agent Harness<br/>[harness.py]"]
  node_context["Constraint Context"]
  node_guardrails["Domain Guardrails<br/>[guardrail.py]"]
end

subgraph group_state["Data and Integrations"]
  node_model{{"Gemini Model"}}
  node_facility_seed["Facility Model<br/>[facility_model.py]"]
  node_signals["External Signals"]
  node_policy["Policy Context<br/>[policy.py]"]
  node_firestore[("Firestore Databases")]
end

node_operator(("Workload Operator"))
node_external_conditions{{"Grid, Weather, Operations"}}

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"submits workload"| node_web_api
node_web_api -->|"forwards negotiation"| node_orchestrator_api
node_web_api -->|"reads history"| node_firestore
node_orchestrator_api -->|"loads workload"| node_firestore
node_orchestrator_api -->|"starts negotiation"| node_orchestrator
node_orchestrator -->|"routes specialist calls"| node_gateway
node_orchestrator -.->|"runs locally"| node_power
node_orchestrator -.->|"runs locally"| node_cooling
node_orchestrator -.->|"runs locally"| node_facilities
node_orchestrator -.->|"runs locally"| node_cost
node_gateway -->|"dispatches"| node_power
node_gateway -->|"dispatches"| node_cooling
node_gateway -->|"dispatches"| node_facilities
node_gateway -->|"dispatches"| node_cost
node_power -->|"invokes"| node_harness
node_cooling -->|"invokes"| node_harness
node_facilities -->|"invokes"| node_harness
node_cost -->|"invokes"| node_harness
node_harness -->|"assembles"| node_context
node_context -->|"reads scoped data"| node_firestore
node_context -->|"incorporates"| node_signals
node_context -->|"incorporates"| node_policy
node_signals -.->|"obtains conditions"| node_external_conditions
node_facility_seed -.->|"seeds facility data"| node_firestore
node_harness -->|"requests verdict"| node_model
node_harness -->|"validates verdict"| node_guardrails
node_guardrails -->|"returns checked verdict"| node_power
node_orchestrator -->|"checks round"| node_consistency
node_consistency -->|"returns conflicts"| node_orchestrator
node_orchestrator -->|"resolves or escalates"| node_decision
node_orchestrator -->|"recalls precedents"| node_firestore
node_orchestrator -->|"records decision"| node_firestore
node_orchestrator_api -->|"renders result"| node_report
node_web_api -->|"renders PDF"| node_report

click node_dashboard "https://github.com/prachit27/gridmindai/blob/main/agents/web/main.py"
click node_web_api "https://github.com/prachit27/gridmindai/blob/main/agents/web/main.py"
click node_orchestrator_api "https://github.com/prachit27/gridmindai/blob/main/agents/orchestrator/main.py"
click node_orchestrator "https://github.com/prachit27/gridmindai/blob/main/agents/orchestrator/orchestrator.py"
click node_consistency "https://github.com/prachit27/gridmindai/blob/main/agents/orchestrator/consistency.py"
click node_decision "https://github.com/prachit27/gridmindai/blob/main/agents/orchestrator/decision.py"
click node_report "https://github.com/prachit27/gridmindai/blob/main/agents/orchestrator/report.py"
click node_gateway "https://github.com/prachit27/gridmindai/blob/main/agents/gateway/main.py"
click node_power "https://github.com/prachit27/gridmindai/blob/main/agents/power/agent.py"
click node_cooling "https://github.com/prachit27/gridmindai/blob/main/agents/cooling/agent.py"
click node_facilities "https://github.com/prachit27/gridmindai/blob/main/agents/facilities/agent.py"
click node_cost "https://github.com/prachit27/gridmindai/blob/main/agents/cost/agent.py"
click node_harness "https://github.com/prachit27/gridmindai/blob/main/agents/common/harness.py"
click node_context "https://github.com/prachit27/gridmindai/blob/main/agents/common/constraint_context.py"
click node_guardrails "https://github.com/prachit27/gridmindai/blob/main/agents/power/guardrail.py"
click node_facility_seed "https://github.com/prachit27/gridmindai/blob/main/seed/facility_model.py"
click node_signals "https://github.com/prachit27/gridmindai/blob/main/agents/common/external_signals.py"
click node_policy "https://github.com/prachit27/gridmindai/blob/main/agents/common/policy.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_dashboard,node_web_api toneBlue
class node_orchestrator_api,node_orchestrator,node_consistency,node_decision,node_report,node_gateway toneAmber
class node_power,node_cooling,node_facilities,node_cost toneMint
class node_harness,node_context,node_guardrails toneRose
class node_model,node_facility_seed,node_signals,node_policy,node_firestore,node_operator,node_external_conditions toneIndigo
```

## Components

### User Entry

- [Dashboard](https://github.com/prachit27/gridmindai/blob/main/agents/web/main.py): `agents/web/main.py`
- [Web API](https://github.com/prachit27/gridmindai/blob/main/agents/web/main.py): `agents/web/main.py`

### Negotiation

- [Negotiation API](https://github.com/prachit27/gridmindai/blob/main/agents/orchestrator/main.py): `agents/orchestrator/main.py`
- [Negotiation Loop](https://github.com/prachit27/gridmindai/blob/main/agents/orchestrator/orchestrator.py): `agents/orchestrator/orchestrator.py`
- [Consistency Check](https://github.com/prachit27/gridmindai/blob/main/agents/orchestrator/consistency.py): `agents/orchestrator/consistency.py`
- [Decision and Escalation](https://github.com/prachit27/gridmindai/blob/main/agents/orchestrator/decision.py): `agents/orchestrator/decision.py`
- [Decision Report](https://github.com/prachit27/gridmindai/blob/main/agents/orchestrator/report.py): `agents/orchestrator/report.py`
- [Agent Gateway](https://github.com/prachit27/gridmindai/blob/main/agents/gateway/main.py): `agents/gateway/main.py`

### Specialists

- [Power Specialist](https://github.com/prachit27/gridmindai/blob/main/agents/power/agent.py): `agents/power/agent.py`
- [Cooling Specialist](https://github.com/prachit27/gridmindai/blob/main/agents/cooling/agent.py): `agents/cooling/agent.py`
- [Facilities Specialist](https://github.com/prachit27/gridmindai/blob/main/agents/facilities/agent.py): `agents/facilities/agent.py`
- [Cost Specialist](https://github.com/prachit27/gridmindai/blob/main/agents/cost/agent.py): `agents/cost/agent.py`

### Agent Harness

- [Shared Agent Harness](https://github.com/prachit27/gridmindai/blob/main/agents/common/harness.py): `agents/common/harness.py`
- [Constraint Context](https://github.com/prachit27/gridmindai/blob/main/agents/common/constraint_context.py): `agents/common/constraint_context.py`
- [Domain Guardrails](https://github.com/prachit27/gridmindai/blob/main/agents/power/guardrail.py): `agents/power/guardrail.py`

### Data and Integrations

- **Gemini Model**
- [Facility Model](https://github.com/prachit27/gridmindai/blob/main/seed/facility_model.py): `seed/facility_model.py`
- [External Signals](https://github.com/prachit27/gridmindai/blob/main/agents/common/external_signals.py): `agents/common/external_signals.py`
- [Policy Context](https://github.com/prachit27/gridmindai/blob/main/agents/common/policy.py): `agents/common/policy.py`
- **Firestore Databases**

### Other components

- **Workload Operator**
- **Grid, Weather, Operations**

## Connections

- Workload Operator → Dashboard: uses
- Dashboard → Web API: submits workload
- Web API → Negotiation API: forwards negotiation
- Web API → Firestore Databases: reads history
- Negotiation API → Firestore Databases: loads workload
- Negotiation API → Negotiation Loop: starts negotiation
- Negotiation Loop → Agent Gateway: routes specialist calls
- Negotiation Loop → Power Specialist: runs locally
- Negotiation Loop → Cooling Specialist: runs locally
- Negotiation Loop → Facilities Specialist: runs locally
- Negotiation Loop → Cost Specialist: runs locally
- Agent Gateway → Power Specialist: dispatches
- Agent Gateway → Cooling Specialist: dispatches
- Agent Gateway → Facilities Specialist: dispatches
- Agent Gateway → Cost Specialist: dispatches
- Power Specialist → Shared Agent Harness: invokes
- Cooling Specialist → Shared Agent Harness: invokes
- Facilities Specialist → Shared Agent Harness: invokes
- Cost Specialist → Shared Agent Harness: invokes
- Shared Agent Harness → Constraint Context: assembles
- Constraint Context → Firestore Databases: reads scoped data
- Constraint Context → External Signals: incorporates
- Constraint Context → Policy Context: incorporates
- External Signals → Grid, Weather, Operations: obtains conditions
- Facility Model → Firestore Databases: seeds facility data
- Shared Agent Harness → Gemini Model: requests verdict
- Shared Agent Harness → Domain Guardrails: validates verdict
- Domain Guardrails → Power Specialist: returns checked verdict
- Negotiation Loop → Consistency Check: checks round
- Consistency Check → Negotiation Loop: returns conflicts
- Negotiation Loop → Decision and Escalation: resolves or escalates
- Negotiation Loop → Firestore Databases: recalls precedents
- Negotiation Loop → Firestore Databases: records decision
- Negotiation API → Decision Report: renders result
- Web API → Decision Report: renders PDF