# baitc-hacks/hack-4078ad52-mama-papa-and-me architecture

> Architecture diagram of the GitHub repository baitc-hacks/hack-4078ad52-mama-papa-and-me, 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-4078ad52-mama-papa-and-me
- Repository: https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me

## Overview

«Аким на 5 часов» — симулятор решений для сравнения влияния инициатив на районы Астаны. Пользователь выбирает меры и районы в интерфейсе; сервер проверяет выбор и рассчитывает отчёт движком. По запросу фоновый процесс готовит AI-разбор с источниками, а сценарий и результат можно сохранить и открыть позже. Карта архитектуры опирается на README и доступные фрагменты исходников; внутренние связи ненаблюдавшихся модулей backend и UI показаны только там, где их подтверждает API-код или документация.

Main entry points: [`src/backend/index.ts`](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/backend/index.ts) (Сервис сценариев и анализа), [`src/ui/features/city-simulator.tsx`](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/ui/features/city-simulator.tsx) (Симулятор города), [`src/engine/index.ts`](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/engine/index.ts) (Проверка и расчёт), [`src/app/api/analyses/route.ts`](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/app/api/analyses/route.ts) (Запуск анализа API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Интерфейс сценария"]
  node_home["Главная страница<br/>[page.tsx]"]
  node_simulator["Симулятор города<br/>[city-simulator.tsx]"]
  node_map["Карта города<br/>[city-map.tsx]"]
  node_evidence["Доказательства"]
  node_preview["Демо интерфейса<br/>[app.tsx]"]
  node_previewapi["Браузерный архив<br/>[browser-api.ts]"]
end

subgraph group_simulation["Модель и расчёт"]
  node_engine["Проверка и расчёт<br/>[index.ts]"]
  node_dataset["Городской датасет<br/>[index.ts]"]
  node_contracts["Контракты данных<br/>[index.ts]"]
end

subgraph group_service["API и обработка"]
  node_simulateapi["Расчёт API<br/>[route.ts]"]
  node_analysisapi["Запуск анализа API<br/>[route.ts]"]
  node_analysisid["Статус анализа API<br/>[route.ts]"]
  node_scenarioapi["Сценарии API<br/>[route.ts]"]
  node_scenarioid["Открытие сценария API<br/>[route.ts]"]
  node_internalapi["Рабочий обработчик API<br/>[route.ts]"]
  node_dispatch["Диспетчер анализа<br/>[dispatch.ts]"]
  node_backend["Сервис сценариев и анализа<br/>[index.ts]"]
  node_config["Конфигурация<br/>[index.ts]"]
  node_background["Фоновая функция"]
end

subgraph group_persistence["Сценарии и хранение"]
  node_storage[("Хранилище сценариев и задач<br/>[index.ts]")]
  node_postgres[("Адаптер Neon PostgreSQL<br/>[postgres.ts]")]
end

subgraph group_advisor["AI-разбор"]
  node_ai["Исследование и объяснение<br/>[index.ts]"]
end

node_user(("Управленец / игрок"))
node_openai["OpenAI и веб-поиск"]

node_user -->|"открывает"| node_home
node_home -->|"показывает"| node_simulator
node_simulator -->|"показывает"| node_map
node_simulator -->|"отправляет выбор"| node_simulateapi
node_simulateapi -->|"проверяет и рассчитывает"| node_engine
node_engine -->|"читает данные"| node_dataset
node_engine -->|"использует типы"| node_contracts
node_simulateapi -->|"возвращает отчёт"| node_simulator
node_simulator -->|"запрашивает разбор"| node_analysisapi
node_analysisapi -->|"создаёт задачу"| node_backend
node_analysisapi -->|"запускает задачу"| node_dispatch
node_dispatch -.->|"передаёт задачу"| node_background
node_dispatch -.->|"вызывает обработчик"| node_internalapi
node_internalapi -->|"обрабатывает задачу"| node_backend
node_analysisid -->|"читает статус"| node_backend
node_analysisid -->|"проверяет режим"| node_config
node_backend -->|"рассчитывает отчёт"| node_engine
node_backend -->|"запрашивает разбор"| node_ai
node_ai -.->|"исследует и объясняет"| node_openai
node_backend -->|"читает и сохраняет"| node_storage
node_backend -->|"читает настройки"| node_config
node_storage -.->|"использует облачный адаптер"| node_postgres
node_analysisapi -->|"принимает запрос"| node_contracts
node_scenarioapi -->|"сохраняет и перечисляет"| node_backend
node_scenarioid -->|"загружает сценарий"| node_backend
node_backend -->|"формирует отчёт сценария"| node_engine
node_scenarioapi -->|"принимает данные сценария"| node_contracts
node_simulator -->|"сохраняет сценарий"| node_scenarioapi
node_simulator -->|"открывает сценарий"| node_scenarioid
node_backend -->|"записывает сценарий"| node_storage
node_analysisid -->|"предоставляет результат"| node_evidence
node_user -.->|"открывает демо"| node_preview
node_preview -.->|"использует архив"| node_previewapi

click node_home "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/app/page.tsx"
click node_simulator "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/ui/features/city-simulator.tsx"
click node_map "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/ui/features/city-map.tsx"
click node_evidence "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/ui/features/scenario-evidence.tsx"
click node_preview "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/ui/preview/app.tsx"
click node_previewapi "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/ui/preview/browser-api.ts"
click node_simulateapi "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/app/api/simulate/route.ts"
click node_analysisapi "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/app/api/analyses/route.ts"
click node_analysisid "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/app/api/analyses/%5Bid%5D/route.ts"
click node_scenarioapi "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/app/api/scenarios/route.ts"
click node_scenarioid "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/app/api/scenarios/%5Bid%5D/route.ts"
click node_internalapi "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/app/api/internal/analyses/%5Bid%5D/route.ts"
click node_dispatch "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/backend/dispatch.ts"
click node_backend "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/backend/index.ts"
click node_engine "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/engine/index.ts"
click node_dataset "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/data/index.ts"
click node_contracts "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/contracts/index.ts"
click node_config "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/config/index.ts"
click node_storage "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/storage/index.ts"
click node_postgres "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/storage/postgres.ts"
click node_ai "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/ai/index.ts"
click node_background "https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/netlify/functions/analysis-background.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_home,node_simulator,node_map,node_evidence,node_preview,node_previewapi toneBlue
class node_engine,node_dataset,node_contracts toneAmber
class node_simulateapi,node_analysisapi,node_analysisid,node_scenarioapi,node_scenarioid,node_internalapi,node_dispatch,node_backend,node_config,node_background toneMint
class node_storage,node_postgres toneRose
class node_ai,node_user,node_openai toneIndigo
```

## Components

### Интерфейс сценария

- [Главная страница](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Симулятор города](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/ui/features/city-simulator.tsx): `src/ui/features/city-simulator.tsx`
- [Карта города](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/ui/features/city-map.tsx): `src/ui/features/city-map.tsx`
- [Доказательства](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/ui/features/scenario-evidence.tsx): `src/ui/features/scenario-evidence.tsx`
- [Демо интерфейса](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/ui/preview/app.tsx): `src/ui/preview/app.tsx`
- [Браузерный архив](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/ui/preview/browser-api.ts): `src/ui/preview/browser-api.ts`

### Модель и расчёт

- [Проверка и расчёт](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/engine/index.ts): `src/engine/index.ts`
- [Городской датасет](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/data/index.ts): `src/data/index.ts`
- [Контракты данных](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/contracts/index.ts): `src/contracts/index.ts`

### API и обработка

- [Расчёт API](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/app/api/simulate/route.ts): `src/app/api/simulate/route.ts`
- [Запуск анализа API](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/app/api/analyses/route.ts): `src/app/api/analyses/route.ts`
- [Статус анализа API](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/app/api/analyses/%5Bid%5D/route.ts): `src/app/api/analyses/[id]/route.ts`
- [Сценарии API](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/app/api/scenarios/route.ts): `src/app/api/scenarios/route.ts`
- [Открытие сценария API](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/app/api/scenarios/%5Bid%5D/route.ts): `src/app/api/scenarios/[id]/route.ts`
- [Рабочий обработчик API](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/app/api/internal/analyses/%5Bid%5D/route.ts): `src/app/api/internal/analyses/[id]/route.ts`
- [Диспетчер анализа](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/backend/dispatch.ts): `src/backend/dispatch.ts`
- [Сервис сценариев и анализа](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/backend/index.ts): `src/backend/index.ts`
- [Конфигурация](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/config/index.ts): `src/config/index.ts`
- [Фоновая функция](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/netlify/functions/analysis-background.ts): `netlify/functions/analysis-background.ts`

### Сценарии и хранение

- [Хранилище сценариев и задач](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/storage/index.ts): `src/storage/index.ts`
- [Адаптер Neon PostgreSQL](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/storage/postgres.ts): `src/storage/postgres.ts`

### AI-разбор

- [Исследование и объяснение](https://github.com/baitc-hacks/hack-4078ad52-mama-papa-and-me/blob/main/src/ai/index.ts): `src/ai/index.ts`

### Other components

- **Управленец / игрок**
- **OpenAI и веб-поиск**

## Connections

- Управленец / игрок → Главная страница: открывает
- Главная страница → Симулятор города: показывает
- Симулятор города → Карта города: показывает
- Симулятор города → Расчёт API: отправляет выбор
- Расчёт API → Проверка и расчёт: проверяет и рассчитывает
- Проверка и расчёт → Городской датасет: читает данные
- Проверка и расчёт → Контракты данных: использует типы
- Расчёт API → Симулятор города: возвращает отчёт
- Симулятор города → Запуск анализа API: запрашивает разбор
- Запуск анализа API → Сервис сценариев и анализа: создаёт задачу
- Запуск анализа API → Диспетчер анализа: запускает задачу
- Диспетчер анализа → Фоновая функция: передаёт задачу
- Диспетчер анализа → Рабочий обработчик API: вызывает обработчик
- Рабочий обработчик API → Сервис сценариев и анализа: обрабатывает задачу
- Статус анализа API → Сервис сценариев и анализа: читает статус
- Статус анализа API → Конфигурация: проверяет режим
- Сервис сценариев и анализа → Проверка и расчёт: рассчитывает отчёт
- Сервис сценариев и анализа → Исследование и объяснение: запрашивает разбор
- Исследование и объяснение → OpenAI и веб-поиск: исследует и объясняет
- Сервис сценариев и анализа → Хранилище сценариев и задач: читает и сохраняет
- Сервис сценариев и анализа → Конфигурация: читает настройки
- Хранилище сценариев и задач → Адаптер Neon PostgreSQL: использует облачный адаптер
- Запуск анализа API → Контракты данных: принимает запрос
- Сценарии API → Сервис сценариев и анализа: сохраняет и перечисляет
- Открытие сценария API → Сервис сценариев и анализа: загружает сценарий
- Сервис сценариев и анализа → Проверка и расчёт: формирует отчёт сценария
- Сценарии API → Контракты данных: принимает данные сценария
- Симулятор города → Сценарии API: сохраняет сценарий
- Симулятор города → Открытие сценария API: открывает сценарий
- Сервис сценариев и анализа → Хранилище сценариев и задач: записывает сценарий
- Статус анализа API → Доказательства: предоставляет результат
- Управленец / игрок → Демо интерфейса: открывает демо
- Демо интерфейса → Браузерный архив: использует архив