# smdanial/bup_hackathon architecture

> Architecture diagram of the GitHub repository smdanial/bup_hackathon, 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/smdanial/bup_hackathon
- Repository: https://github.com/smdanial/bup_hackathon

## Overview

GridWise is an energy-scheduling API: a caller submits a 24-hour demand, solar, tariff, battery, and operator-note scenario, and receives interpreted directives plus an optimized hourly plan and cost metrics. The workflow validates the request, interprets notes, checks directive guardrails, then solves the schedule. The sampled source shows these stages and their calls; the README provides no additional capability detail, and the frontend file was not sampled.

Main entry points: [`app/services/optimize.py`](https://github.com/smdanial/bup_hackathon/blob/main/app/services/optimize.py) (Optimization Service), [`app/api/routes.py`](https://github.com/smdanial/bup_hackathon/blob/main/app/api/routes.py) (Optimization Endpoint), [`app/llm/interpreter.py`](https://github.com/smdanial/bup_hackathon/blob/main/app/llm/interpreter.py) (Note Interpreter), [`app/optimizer/solver.py`](https://github.com/smdanial/bup_hackathon/blob/main/app/optimizer/solver.py) (Schedule Solver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_routes["Optimization Endpoint<br/>[routes.py]"]
  node_service["Optimization Service<br/>[optimize.py]"]
end

subgraph group_directives["Directive Processing"]
  node_interpreter["Note Interpreter<br/>[interpreter.py]"]
  node_validator["Directive Guardrails<br/>[directives.py]"]
end

subgraph group_optimization["Schedule Optimization"]
  node_solver["Schedule Solver<br/>[solver.py]"]
end

subgraph group_contracts["Data Contracts"]
  node_request["Request and Response Models<br/>[schemas.py]"]
end

node_caller(("API Caller"))
node_gemini["Gemini API"]

node_caller -->|"submits scenario"| node_routes
node_routes -->|"validates body"| node_request
node_routes -->|"calls"| node_service
node_service -->|"interprets notes"| node_interpreter
node_interpreter -.->|"requests directives"| node_gemini
node_service -->|"checks directives"| node_validator
node_service -->|"builds schedule"| node_solver
node_solver -->|"returns plan"| node_service
node_service -->|"returns result"| node_routes
node_routes -->|"returns response"| node_caller

click node_routes "https://github.com/smdanial/bup_hackathon/blob/main/app/api/routes.py"
click node_service "https://github.com/smdanial/bup_hackathon/blob/main/app/services/optimize.py"
click node_request "https://github.com/smdanial/bup_hackathon/blob/main/app/models/schemas.py"
click node_interpreter "https://github.com/smdanial/bup_hackathon/blob/main/app/llm/interpreter.py"
click node_validator "https://github.com/smdanial/bup_hackathon/blob/main/app/validation/directives.py"
click node_solver "https://github.com/smdanial/bup_hackathon/blob/main/app/optimizer/solver.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_routes,node_service toneBlue
class node_interpreter,node_validator toneAmber
class node_solver,node_caller,node_gemini toneMint
class node_request toneRose
```

## Components

### API

- [Optimization Endpoint](https://github.com/smdanial/bup_hackathon/blob/main/app/api/routes.py): `app/api/routes.py`
- [Optimization Service](https://github.com/smdanial/bup_hackathon/blob/main/app/services/optimize.py): `app/services/optimize.py`

### Directive Processing

- [Note Interpreter](https://github.com/smdanial/bup_hackathon/blob/main/app/llm/interpreter.py): `app/llm/interpreter.py`
- [Directive Guardrails](https://github.com/smdanial/bup_hackathon/blob/main/app/validation/directives.py): `app/validation/directives.py`

### Schedule Optimization

- [Schedule Solver](https://github.com/smdanial/bup_hackathon/blob/main/app/optimizer/solver.py): `app/optimizer/solver.py`

### Data Contracts

- [Request and Response Models](https://github.com/smdanial/bup_hackathon/blob/main/app/models/schemas.py): `app/models/schemas.py`

### Other components

- **API Caller**
- **Gemini API**

## Connections

- API Caller → Optimization Endpoint: submits scenario
- Optimization Endpoint → Request and Response Models: validates body
- Optimization Endpoint → Optimization Service: calls
- Optimization Service → Note Interpreter: interprets notes
- Note Interpreter → Gemini API: requests directives
- Optimization Service → Directive Guardrails: checks directives
- Optimization Service → Schedule Solver: builds schedule
- Schedule Solver → Optimization Service: returns plan
- Optimization Service → Optimization Endpoint: returns result
- Optimization Endpoint → API Caller: returns response