# baitc-hacks/hack-ec7c49fc-edu-ai architecture

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

- Interactive diagram: https://gitdiagram.com/baitc-hacks/hack-ec7c49fc-edu-ai
- Repository: https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai

## Overview

Astana AI is a city-planning decision-support app: a manager builds or requests a budget-constrained set of district and city measures, then sees deterministic before/after impacts and can compare and apply alternatives. The manual builder invokes the simulation directly; the advisor API coordinates goal interpretation, candidate search, simulation, and grounded explanation. The README documents optional OpenAI use with deterministic fallback. Some advisor internals were not sampled, so those documented stages are shown without assuming details beyond that flow.

Main entry points: [`src/lib/simulation/engine.ts`](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/simulation/engine.ts) (Simulation engine), [`src/lib/agent/advisor.ts`](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/agent/advisor.ts) (Advisor orchestration), [`src/components/dashboard/Dashboard.tsx`](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/components/dashboard/Dashboard.tsx) (Dashboard), [`src/components/dashboard/AdvisorPanel.tsx`](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/components/dashboard/AdvisorPanel.tsx) (Advisor panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard and planning"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_builder["Scenario builder"]
  node_results["Impact results"]
  node_advisor_panel["Advisor panel<br/>[AdvisorPanel.tsx]"]
end

subgraph group_advisor["Advisor workflow"]
  node_advisor_api["Advisor API<br/>[route.ts]"]
  node_advisor["Advisor orchestration<br/>[advisor.ts]"]
  node_objective["Goal interpretation<br/>[objective.ts]"]
  node_analysis["Plan analysis<br/>[analysis.ts]"]
  node_explanation["Grounded explanation<br/>[explanation.ts]"]
  node_prompts["Model prompts<br/>[prompts.ts]"]
end

subgraph group_search["Scenario optimization"]
  node_optimizer["Candidate search<br/>[optimizer.ts]"]
  node_catalog["Measure search catalog<br/>[catalog.ts]"]
end

subgraph group_simulation["Simulation and data"]
  node_engine["Simulation engine<br/>[engine.ts]"]
  node_validation["Scenario validation<br/>[validator.ts]"]
  node_scoring["Scoring rules<br/>[score.ts]"]
  node_district_data["District baselines<br/>[districts.ts]"]
  node_indicator_data["Indicator definitions<br/>[indicators.ts]"]
  node_measure_data["Measure catalog<br/>[measures.ts]"]
  node_domain_types["Domain contracts<br/>[domain.ts]"]
end

node_manager(("City manager"))
node_openai["OpenAI API"]

node_manager -->|"uses"| node_dashboard
node_dashboard -->|"renders"| node_builder
node_dashboard -->|"renders"| node_results
node_dashboard -->|"renders"| node_advisor_panel
node_dashboard -->|"calculates baseline and plan"| node_engine
node_builder -->|"previews plan"| node_engine
node_results -->|"shows impacts"| node_manager
node_advisor_panel -->|"submits goal and plan"| node_advisor_api
node_advisor_panel -->|"checks candidate"| node_engine
node_advisor_api -->|"invokes"| node_advisor
node_advisor_api -->|"simulates current plan"| node_engine
node_advisor -->|"interprets goal"| node_objective
node_advisor -->|"searches alternatives"| node_optimizer
node_advisor -->|"simulates current plan"| node_engine
node_advisor -->|"analyzes results"| node_analysis
node_advisor -->|"explains findings"| node_explanation
node_advisor -.->|"interprets or selects facts"| node_openai
node_objective -.->|"interprets free text"| node_openai
node_explanation -.->|"selects supporting facts"| node_openai
node_advisor -.->|"uses prompts"| node_prompts
node_optimizer -->|"reads search definitions"| node_catalog
node_optimizer -->|"evaluates candidates"| node_engine
node_analysis -->|"compares candidate quality"| node_optimizer
node_engine -->|"validates and costs plan"| node_validation
node_engine -->|"calculates scores"| node_scoring
node_engine -->|"reads baselines"| node_district_data
node_engine -->|"reads indicators"| node_indicator_data
node_engine -->|"reads measure effects"| node_measure_data
node_engine -->|"returns simulation results"| node_manager
node_advisor -->|"returns alternatives and explanation"| node_advisor_panel
node_advisor_panel -->|"applies selected plan"| node_dashboard

click node_dashboard "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/components/dashboard/Dashboard.tsx"
click node_builder "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/components/scenario/ScenarioBuilder.tsx"
click node_results "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/components/dashboard/SimulationResults.tsx"
click node_advisor_panel "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/components/dashboard/AdvisorPanel.tsx"
click node_advisor_api "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/app/api/advisor/route.ts"
click node_advisor "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/agent/advisor.ts"
click node_objective "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/agent/objective.ts"
click node_optimizer "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/optimizer/optimizer.ts"
click node_catalog "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/optimizer/catalog.ts"
click node_analysis "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/agent/analysis.ts"
click node_explanation "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/agent/explanation.ts"
click node_prompts "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/agent/prompts.ts"
click node_engine "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/simulation/engine.ts"
click node_validation "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/simulation/validator.ts"
click node_scoring "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/simulation/score.ts"
click node_district_data "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/data/districts.ts"
click node_indicator_data "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/data/indicators.ts"
click node_measure_data "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/data/measures.ts"
click node_domain_types "https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/types/domain.ts"

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_builder,node_results,node_advisor_panel toneBlue
class node_advisor_api,node_advisor,node_objective,node_analysis,node_explanation,node_prompts toneAmber
class node_optimizer,node_catalog,node_openai toneMint
class node_engine,node_validation,node_scoring,node_district_data,node_indicator_data,node_measure_data,node_domain_types toneRose
class node_manager toneIndigo
```

## Components

### Dashboard and planning

- [Dashboard](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/components/dashboard/Dashboard.tsx): `src/components/dashboard/Dashboard.tsx`
- [Scenario builder](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/components/scenario/ScenarioBuilder.tsx): `src/components/scenario/ScenarioBuilder.tsx`
- [Impact results](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/components/dashboard/SimulationResults.tsx): `src/components/dashboard/SimulationResults.tsx`
- [Advisor panel](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/components/dashboard/AdvisorPanel.tsx): `src/components/dashboard/AdvisorPanel.tsx`

### Advisor workflow

- [Advisor API](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/app/api/advisor/route.ts): `src/app/api/advisor/route.ts`
- [Advisor orchestration](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/agent/advisor.ts): `src/lib/agent/advisor.ts`
- [Goal interpretation](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/agent/objective.ts): `src/lib/agent/objective.ts`
- [Plan analysis](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/agent/analysis.ts): `src/lib/agent/analysis.ts`
- [Grounded explanation](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/agent/explanation.ts): `src/lib/agent/explanation.ts`
- [Model prompts](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/agent/prompts.ts): `src/lib/agent/prompts.ts`

### Scenario optimization

- [Candidate search](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/optimizer/optimizer.ts): `src/lib/optimizer/optimizer.ts`
- [Measure search catalog](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/optimizer/catalog.ts): `src/lib/optimizer/catalog.ts`

### Simulation and data

- [Simulation engine](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/simulation/engine.ts): `src/lib/simulation/engine.ts`
- [Scenario validation](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/simulation/validator.ts): `src/lib/simulation/validator.ts`
- [Scoring rules](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/lib/simulation/score.ts): `src/lib/simulation/score.ts`
- [District baselines](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/data/districts.ts): `src/data/districts.ts`
- [Indicator definitions](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/data/indicators.ts): `src/data/indicators.ts`
- [Measure catalog](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/data/measures.ts): `src/data/measures.ts`
- [Domain contracts](https://github.com/baitc-hacks/hack-ec7c49fc-edu-ai/blob/main/src/types/domain.ts): `src/types/domain.ts`

### Other components

- **City manager**
- **OpenAI API**

## Connections

- City manager → Dashboard: uses
- Dashboard → Scenario builder: renders
- Dashboard → Impact results: renders
- Dashboard → Advisor panel: renders
- Dashboard → Simulation engine: calculates baseline and plan
- Scenario builder → Simulation engine: previews plan
- Impact results → City manager: shows impacts
- Advisor panel → Advisor API: submits goal and plan
- Advisor panel → Simulation engine: checks candidate
- Advisor API → Advisor orchestration: invokes
- Advisor API → Simulation engine: simulates current plan
- Advisor orchestration → Goal interpretation: interprets goal
- Advisor orchestration → Candidate search: searches alternatives
- Advisor orchestration → Simulation engine: simulates current plan
- Advisor orchestration → Plan analysis: analyzes results
- Advisor orchestration → Grounded explanation: explains findings
- Advisor orchestration → OpenAI API: interprets or selects facts
- Goal interpretation → OpenAI API: interprets free text
- Grounded explanation → OpenAI API: selects supporting facts
- Advisor orchestration → Model prompts: uses prompts
- Candidate search → Measure search catalog: reads search definitions
- Candidate search → Simulation engine: evaluates candidates
- Plan analysis → Candidate search: compares candidate quality
- Simulation engine → Scenario validation: validates and costs plan
- Simulation engine → Scoring rules: calculates scores
- Simulation engine → District baselines: reads baselines
- Simulation engine → Indicator definitions: reads indicators
- Simulation engine → Measure catalog: reads measure effects
- Simulation engine → City manager: returns simulation results
- Advisor orchestration → Advisor panel: returns alternatives and explanation
- Advisor panel → Dashboard: applies selected plan