# mdhabibullahmahmudncs13/bup-hackathon-preliminary-round architecture

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

- Interactive diagram: https://gitdiagram.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round
- Repository: https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round

## Overview

GridWise is an HTTP service that turns campus operators’ scenario data and natural-language notes into a validated, cost-minimal 24-hour energy schedule. The main path accepts and validates a request, interprets each note with OpenRouter (falling back to deterministic parsing when needed), solves the resulting constraints as a battery-aware MILP, then independently replays the plan before returning it. The README also documents a dashboard, health endpoint, and retry cache. Some wiring is inferred from explicit README pipeline documentation; unsampled route and response details are not expanded.

Main entry points: [`app/main.py`](https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/main.py) (API pipeline), [`app/llm.py`](https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/llm.py) (LLM client), [`app/optimizer.py`](https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/optimizer.py) (MILP optimizer), [`app/models.py`](https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/models.py) (Request and response schemas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP service"]
  node_service["API pipeline<br/>[main.py]"]
  node_schemas["Request and response schemas<br/>[models.py]"]
  node_dashboard["Control-room dashboard<br/>[ui.html]"]
  node_cache[("Response cache<br/>[main.py]")]
  node_response["Schedule response<br/>[models.py]"]
end

subgraph group_interpret["Directive interpretation"]
  node_llm_interpret["LLM client<br/>[llm.py]"]
  node_guardrails["Directive guardrails<br/>[main.py]"]
  node_fallback["Heuristic interpreter"]
  node_settings["Provider settings<br/>[settings.py]"]
end

subgraph group_solve["Schedule optimization"]
  node_optimizer["MILP optimizer<br/>[optimizer.py]"]
  node_replay["Plan replay<br/>[optimizer.py]"]
end

subgraph group_verify["Plan verification"]
  node_validator["Independent validator<br/>[validator.py]"]
end

node_operator(("Operator"))
node_openrouter{{"OpenRouter"}}
node_solver{{"PuLP and CBC"}}
node_browser(("Browser client"))

node_operator -->|"submits scenario"| node_service
node_service -->|"validates request"| node_schemas
node_service -->|"checks and stores"| node_cache
node_service -->|"requests interpretation"| node_llm_interpret
node_llm_interpret -->|"reads configuration"| node_settings
node_llm_interpret -->|"sends notes"| node_openrouter
node_openrouter -->|"returns proposals"| node_llm_interpret
node_service -->|"checks proposals"| node_guardrails
node_guardrails -->|"validates directives"| node_schemas
node_guardrails -->|"falls back per note"| node_fallback
node_service -->|"falls back on LLM failure"| node_fallback
node_service -->|"passes request and directives"| node_optimizer
node_optimizer -->|"solves MILP"| node_solver
node_optimizer -->|"replays solution"| node_replay
node_service -->|"checks final plan"| node_validator
node_service -->|"builds response"| node_response
node_response -->|"validates response"| node_schemas
node_service -->|"serves dashboard"| node_dashboard
node_browser -->|"requests API or UI"| node_service
node_service -->|"returns schedule or UI"| node_browser

click node_service "https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/main.py"
click node_schemas "https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/models.py"
click node_dashboard "https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/static/ui.html"
click node_cache "https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/main.py"
click node_llm_interpret "https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/llm.py"
click node_guardrails "https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/main.py"
click node_fallback "https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/fallback_interpreter.py"
click node_settings "https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/settings.py"
click node_optimizer "https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/optimizer.py"
click node_replay "https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/optimizer.py"
click node_validator "https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/validator.py"
click node_response "https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/models.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_service,node_schemas,node_dashboard,node_cache,node_response,node_browser toneBlue
class node_llm_interpret,node_guardrails,node_fallback,node_settings toneAmber
class node_optimizer,node_replay,node_openrouter toneMint
class node_validator toneRose
class node_operator,node_solver toneIndigo
```

## Components

### HTTP service

- [API pipeline](https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/main.py): `app/main.py`
- [Request and response schemas](https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/models.py): `app/models.py`
- [Control-room dashboard](https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/static/ui.html): `app/static/ui.html`
- [Response cache](https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/main.py): `app/main.py`
- [Schedule response](https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/models.py): `app/models.py`

### Directive interpretation

- [LLM client](https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/llm.py): `app/llm.py`
- [Directive guardrails](https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/main.py): `app/main.py`
- [Heuristic interpreter](https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/fallback_interpreter.py): `app/fallback_interpreter.py`
- [Provider settings](https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/settings.py): `app/settings.py`

### Schedule optimization

- [MILP optimizer](https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/optimizer.py): `app/optimizer.py`
- [Plan replay](https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/optimizer.py): `app/optimizer.py`

### Plan verification

- [Independent validator](https://github.com/mdhabibullahmahmudncs13/bup-hackathon-preliminary-round/blob/main/app/validator.py): `app/validator.py`

### Other components

- **Operator**
- **OpenRouter**
- **PuLP and CBC**
- **Browser client**

## Connections

- Operator → API pipeline: submits scenario
- API pipeline → Request and response schemas: validates request
- API pipeline → Response cache: checks and stores
- API pipeline → LLM client: requests interpretation
- LLM client → Provider settings: reads configuration
- LLM client → OpenRouter: sends notes
- OpenRouter → LLM client: returns proposals
- API pipeline → Directive guardrails: checks proposals
- Directive guardrails → Request and response schemas: validates directives
- Directive guardrails → Heuristic interpreter: falls back per note
- API pipeline → Heuristic interpreter: falls back on LLM failure
- API pipeline → MILP optimizer: passes request and directives
- MILP optimizer → PuLP and CBC: solves MILP
- MILP optimizer → Plan replay: replays solution
- API pipeline → Independent validator: checks final plan
- API pipeline → Schedule response: builds response
- Schedule response → Request and response schemas: validates response
- API pipeline → Control-room dashboard: serves dashboard
- Browser client → API pipeline: requests API or UI
- API pipeline → Browser client: returns schedule or UI