# baitc-hacks/hack-e54d9694-that-day-in architecture

> Architecture diagram of the GitHub repository baitc-hacks/hack-e54d9694-that-day-in, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/baitc-hacks/hack-e54d9694-that-day-in
- Repository: https://github.com/baitc-hacks/hack-e54d9694-that-day-in

## Overview

That Day is an AI-assisted city-governance simulator: participants build a five-measure, budget-constrained plan for Astana districts, inspect projected effects, then calculate and explore a report. The graph preserves separate practice-event, recommendation, participant-ranking, presentation, and experimental review-analysis capabilities documented in the README. Several API handlers and UI state modules were not excerpted; their links are included only where the README or SOURCE INDEX supports them.

Main entry points: [`src/components/city-workspace.tsx`](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/components/city-workspace.tsx) (City workspace), [`src/app/api/_lib/scenario.ts`](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/app/api/_lib/scenario.ts) (Scenario API), [`src/lib/simulation/index.ts`](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/simulation/index.ts) (Scenario simulation), [`src/app/api/events/simulate/route.ts`](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/app/api/events/simulate/route.ts) (Event APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Planning experience"]
  node_workspace["City workspace<br/>[city-workspace.tsx]"]
  node_map["Interactive map<br/>[city-map.tsx]"]
  node_map_studio["Map studio<br/>[map-studio.tsx]"]
  node_scenario_tools["Scenario tools<br/>[scenario-tools.tsx]"]
  node_map_state["Map event state<br/>[use-playground.ts]"]
  node_report_state["Report state<br/>[use-report.ts]"]
  node_request_client["API request client<br/>[client.ts]"]
end

subgraph group_model["Simulation model"]
  node_simulation["Scenario simulation<br/>[index.ts]"]
  node_map_events_model["Map event simulation<br/>[map-events.ts]"]
  node_events_data["Practice events<br/>[events.ts]"]
  node_feedback_projection["Feedback projection<br/>[projection.ts]"]
end

subgraph group_api["Server API"]
  node_catalog_api["Catalog API<br/>[route.ts]"]
  node_scenario_api["Scenario API<br/>[scenario.ts]"]
  node_event_api["Event APIs<br/>[route.ts]"]
end

subgraph group_insights["Analysis features"]
  node_ai_analysis["AI analysis<br/>[analyze.ts]"]
  node_recommendations["Recommendations<br/>[recommendations.ts]"]
  node_leaderboard[("Participant leaderboard<br/>[store.ts]")]
  node_presentation["Presentation generation<br/>[presentation.ts]"]
  node_reviews["Review signal extraction<br/>[reviews.ts]"]
end

subgraph group_state["Data and state"]
  node_catalog["City dataset<br/>[index.ts]"]
  node_contracts["Shared contracts<br/>[contracts.ts]"]
  node_feature_contracts["Feature contracts<br/>[features.ts]"]
end

node_participant(("City planner"))

node_participant -->|"builds plan"| node_workspace
node_workspace -->|"renders"| node_map_studio
node_map_studio -->|"renders"| node_map
node_workspace -->|"offers"| node_scenario_tools
node_workspace -->|"uses"| node_report_state
node_workspace -->|"uses"| node_map_state
node_workspace -.->|"requests"| node_request_client
node_request_client -->|"fetches catalog"| node_catalog_api
node_request_client -->|"posts scenario"| node_scenario_api
node_catalog_api -->|"reads catalog"| node_scenario_api
node_scenario_api -->|"loads data"| node_catalog
node_scenario_api -->|"validates request"| node_contracts
node_scenario_api -->|"simulates plan"| node_simulation
node_scenario_tools -->|"previews plan"| node_simulation
node_simulation -.->|"calculates from"| node_catalog
node_map_state -->|"simulates events"| node_map_events_model
node_map_events_model -->|"uses event data"| node_events_data
node_event_api -->|"selects event"| node_events_data
node_event_api -->|"simulates event"| node_simulation
node_event_api -->|"validates event"| node_feature_contracts
node_participant -.->|"requests explanation"| node_ai_analysis
node_ai_analysis -.->|"receives calculated facts"| node_scenario_api
node_participant -.->|"explores alternatives"| node_recommendations
node_participant -.->|"publishes result"| node_leaderboard
node_participant -.->|"creates slides"| node_presentation
node_participant -.->|"submits feedback"| node_reviews
node_reviews -->|"validates signals"| node_feedback_projection
node_feedback_projection -->|"projects changes"| node_simulation
node_recommendations -.->|"evaluates candidates"| node_simulation

click node_workspace "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/components/city-workspace.tsx"
click node_map "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/components/city-map.tsx"
click node_map_studio "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/components/map-studio.tsx"
click node_scenario_tools "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/components/scenario-tools.tsx"
click node_map_state "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/features/map/use-playground.ts"
click node_report_state "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/features/simulator/use-report.ts"
click node_request_client "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/features/scenario-tools/client.ts"
click node_catalog "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/data/index.ts"
click node_contracts "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/shared/contracts.ts"
click node_feature_contracts "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/shared/features.ts"
click node_simulation "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/simulation/index.ts"
click node_map_events_model "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/simulation/map-events.ts"
click node_events_data "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/data/events.ts"
click node_catalog_api "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/app/api/catalog/route.ts"
click node_scenario_api "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/app/api/_lib/scenario.ts"
click node_event_api "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/app/api/events/simulate/route.ts"
click node_ai_analysis "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/ai/analyze.ts"
click node_recommendations "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/simulation/recommendations.ts"
click node_leaderboard "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/competition/store.ts"
click node_presentation "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/simulation/presentation.ts"
click node_reviews "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/ai/reviews.ts"
click node_feedback_projection "https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/feedback/projection.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_workspace,node_map,node_map_studio,node_scenario_tools,node_map_state,node_report_state,node_request_client toneBlue
class node_simulation,node_map_events_model,node_events_data,node_feedback_projection toneAmber
class node_catalog_api,node_scenario_api,node_event_api toneMint
class node_ai_analysis,node_recommendations,node_leaderboard,node_presentation,node_reviews toneRose
class node_catalog,node_contracts,node_feature_contracts,node_participant toneIndigo
```

## Components

### Planning experience

- [City workspace](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/components/city-workspace.tsx): `src/components/city-workspace.tsx`
- [Interactive map](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/components/city-map.tsx): `src/components/city-map.tsx`
- [Map studio](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/components/map-studio.tsx): `src/components/map-studio.tsx`
- [Scenario tools](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/components/scenario-tools.tsx): `src/components/scenario-tools.tsx`
- [Map event state](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/features/map/use-playground.ts): `src/features/map/use-playground.ts`
- [Report state](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/features/simulator/use-report.ts): `src/features/simulator/use-report.ts`
- [API request client](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/features/scenario-tools/client.ts): `src/features/scenario-tools/client.ts`

### Simulation model

- [Scenario simulation](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/simulation/index.ts): `src/lib/simulation/index.ts`
- [Map event simulation](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/simulation/map-events.ts): `src/lib/simulation/map-events.ts`
- [Practice events](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/data/events.ts): `src/data/events.ts`
- [Feedback projection](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/feedback/projection.ts): `src/lib/feedback/projection.ts`

### Server API

- [Catalog API](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/app/api/catalog/route.ts): `src/app/api/catalog/route.ts`
- [Scenario API](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/app/api/_lib/scenario.ts): `src/app/api/_lib/scenario.ts`
- [Event APIs](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/app/api/events/simulate/route.ts): `src/app/api/events/simulate/route.ts`

### Analysis features

- [AI analysis](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/ai/analyze.ts): `src/lib/ai/analyze.ts`
- [Recommendations](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/simulation/recommendations.ts): `src/lib/simulation/recommendations.ts`
- [Participant leaderboard](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/competition/store.ts): `src/lib/competition/store.ts`
- [Presentation generation](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/simulation/presentation.ts): `src/lib/simulation/presentation.ts`
- [Review signal extraction](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/lib/ai/reviews.ts): `src/lib/ai/reviews.ts`

### Data and state

- [City dataset](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/data/index.ts): `src/data/index.ts`
- [Shared contracts](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/shared/contracts.ts): `src/shared/contracts.ts`
- [Feature contracts](https://github.com/baitc-hacks/hack-e54d9694-that-day-in/blob/main/src/shared/features.ts): `src/shared/features.ts`

### Other components

- **City planner**

## Connections

- City planner → City workspace: builds plan
- City workspace → Map studio: renders (evidence: `src/components/city-workspace.tsx`)
- Map studio → Interactive map: renders (evidence: `src/components/map-studio.tsx`)
- City workspace → Scenario tools: offers (evidence: `src/components/city-workspace.tsx`)
- City workspace → Report state: uses (evidence: `src/components/city-workspace.tsx`)
- City workspace → Map event state: uses (evidence: `src/components/city-workspace.tsx`)
- City workspace → API request client: requests (evidence: `src/components/city-workspace.tsx`)
- API request client → Catalog API: fetches catalog (evidence: `src/features/scenario-tools/client.ts`)
- API request client → Scenario API: posts scenario (evidence: `src/features/scenario-tools/client.ts`)
- Catalog API → Scenario API: reads catalog (evidence: `src/app/api/catalog/route.ts`)
- Scenario API → City dataset: loads data (evidence: `src/app/api/_lib/scenario.ts`)
- Scenario API → Shared contracts: validates request (evidence: `src/app/api/_lib/scenario.ts`)
- Scenario API → Scenario simulation: simulates plan (evidence: `src/app/api/_lib/scenario.ts`)
- Scenario tools → Scenario simulation: previews plan (evidence: `src/components/scenario-tools.tsx`)
- Scenario simulation → City dataset: calculates from
- Map event state → Map event simulation: simulates events (evidence: `src/features/map/use-playground.ts`)
- Map event simulation → Practice events: uses event data (evidence: `src/lib/simulation/map-events.ts`)
- Event APIs → Practice events: selects event (evidence: `src/app/api/events/simulate/route.ts`)
- Event APIs → Scenario simulation: simulates event (evidence: `src/app/api/events/simulate/route.ts`)
- Event APIs → Feature contracts: validates event (evidence: `src/app/api/events/simulate/route.ts`)
- City planner → AI analysis: requests explanation
- AI analysis → Scenario API: receives calculated facts
- City planner → Recommendations: explores alternatives
- City planner → Participant leaderboard: publishes result
- City planner → Presentation generation: creates slides
- City planner → Review signal extraction: submits feedback
- Review signal extraction → Feedback projection: validates signals (evidence: `src/lib/ai/reviews.ts`)
- Feedback projection → Scenario simulation: projects changes (evidence: `src/lib/feedback/projection.ts`)
- Recommendations → Scenario simulation: evaluates candidates
