# shaswatabarua/bup-cse-fest-2026-gridwise architecture

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

- Interactive diagram: https://gitdiagram.com/shaswatabarua/bup-cse-fest-2026-gridwise
- Repository: https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise

## Overview

GridWise accepts a 24-hour campus energy scenario and operator notes, interprets the notes as directives, validates them, and optimizes a battery-aware schedule to minimize grid cost. Its main path is the FastAPI optimization endpoint through interpretation, guardrails, and the PuLP/CBC solver, then back as hourly plan and totals. The README also documents deterministic fallback parsing, in-memory caching, and an optional Gemini provider. Those capabilities are represented from documentation and sampled code; deployment and test infrastructure are omitted.

Main entry points: [`app/main.py`](https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/main.py) (GridWise API), [`app/llm_interpreter.py`](https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/llm_interpreter.py) (Note interpreter), [`app/optimizer.py`](https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/optimizer.py) (Schedule optimizer), [`app/schemas.py`](https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/schemas.py) (Request and response schemas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and contracts"]
  node_fastapi["GridWise API<br/>[main.py]"]
  node_schemas["Request and response schemas<br/>[schemas.py]"]
end

subgraph group_interpretation["Note interpretation"]
  node_interpreter["Note interpreter<br/>[llm_interpreter.py]"]
  node_config["Provider settings<br/>[config.py]"]
  node_fallback["Deterministic parser<br/>[llm_interpreter.py]"]
  node_cache[("Interpretation cache<br/>[llm_interpreter.py]")]
  node_guardrails["Directive guardrails<br/>[guardrails.py]"]
end

subgraph group_optimization["Schedule optimization"]
  node_optimizer["Schedule optimizer<br/>[optimizer.py]"]
end

subgraph group_integrations["External services"]
  node_cbc["CBC solver"]
  node_groq["Groq model service"]
  node_gemini["Gemini model service"]
end

node_operator(("Campus operator"))

node_operator -->|"submits scenario"| node_fastapi
node_fastapi -->|"validates request"| node_schemas
node_fastapi -->|"interprets notes"| node_interpreter
node_interpreter -->|"reads settings"| node_config
node_interpreter -->|"checks and updates"| node_cache
node_interpreter -->|"calls when selected"| node_groq
node_interpreter -.->|"calls when selected"| node_gemini
node_interpreter -->|"falls back on error"| node_fallback
node_interpreter -->|"returns directives"| node_fastapi
node_fastapi -->|"validates directives"| node_guardrails
node_fastapi -->|"solves schedule"| node_optimizer
node_optimizer -->|"solves model"| node_cbc
node_optimizer -->|"returns plan and totals"| node_fastapi
node_fastapi -->|"returns JSON result"| node_operator

click node_fastapi "https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/main.py"
click node_schemas "https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/schemas.py"
click node_interpreter "https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/llm_interpreter.py"
click node_config "https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/config.py"
click node_fallback "https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/llm_interpreter.py"
click node_cache "https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/llm_interpreter.py"
click node_guardrails "https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/guardrails.py"
click node_optimizer "https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/optimizer.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_fastapi,node_schemas toneBlue
class node_interpreter,node_config,node_fallback,node_cache,node_guardrails toneAmber
class node_optimizer toneMint
class node_cbc,node_groq,node_gemini toneRose
class node_operator toneIndigo
```

## Components

### API and contracts

- [GridWise API](https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/main.py): `app/main.py`
- [Request and response schemas](https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/schemas.py): `app/schemas.py`

### Note interpretation

- [Note interpreter](https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/llm_interpreter.py): `app/llm_interpreter.py`
- [Provider settings](https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/config.py): `app/config.py`
- [Deterministic parser](https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/llm_interpreter.py): `app/llm_interpreter.py`
- [Interpretation cache](https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/llm_interpreter.py): `app/llm_interpreter.py`
- [Directive guardrails](https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/guardrails.py): `app/guardrails.py`

### Schedule optimization

- [Schedule optimizer](https://github.com/shaswatabarua/bup-cse-fest-2026-gridwise/blob/main/app/optimizer.py): `app/optimizer.py`

### External services

- **CBC solver**
- **Groq model service**
- **Gemini model service**

### Other components

- **Campus operator**

## Connections

- Campus operator → GridWise API: submits scenario
- GridWise API → Request and response schemas: validates request
- GridWise API → Note interpreter: interprets notes
- Note interpreter → Provider settings: reads settings
- Note interpreter → Interpretation cache: checks and updates
- Note interpreter → Groq model service: calls when selected
- Note interpreter → Gemini model service: calls when selected
- Note interpreter → Deterministic parser: falls back on error
- Note interpreter → GridWise API: returns directives
- GridWise API → Directive guardrails: validates directives
- GridWise API → Schedule optimizer: solves schedule
- Schedule optimizer → CBC solver: solves model
- Schedule optimizer → GridWise API: returns plan and totals
- GridWise API → Campus operator: returns JSON result