How baitc-hacks/hack-ec7c49fc-edu-ai works
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: engine.ts Simulation engine · advisor.ts Advisor orchestration · Dashboard.tsx Dashboard · AdvisorPanel.tsx Advisor panel
Components 21
Dashboard and planning
- Dashboard
src/components/dashboard/Dashboard.tsx - Scenario builder
src/components/scenario/ScenarioBuilder.tsx - Impact results
src/components/dashboard/SimulationResults.tsx - Advisor panel
src/components/dashboard/AdvisorPanel.tsx
Advisor workflow
- Advisor API
src/app/api/advisor/route.ts - Advisor orchestration
src/lib/agent/advisor.ts - Goal interpretation
src/lib/agent/objective.ts - Plan analysis
src/lib/agent/analysis.ts - Grounded explanation
src/lib/agent/explanation.ts - Model prompts
src/lib/agent/prompts.ts
Scenario optimization
- Candidate search
src/lib/optimizer/optimizer.ts - Measure search catalog
src/lib/optimizer/catalog.ts
Simulation and data
- Simulation engine
src/lib/simulation/engine.ts - Scenario validation
src/lib/simulation/validator.ts - Scoring rules
src/lib/simulation/score.ts - District baselines
src/data/districts.ts - Indicator definitions
src/data/indicators.ts - Measure catalog
src/data/measures.ts - Domain contracts
src/types/domain.ts
Other components
- City manager
- OpenAI API
Connections 31
- 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