# hard-sign-hackaton/employer_first_roadmap architecture

> Architecture diagram of the GitHub repository hard-sign-hackaton/employer_first_roadmap, 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/hard-sign-hackaton/employer_first_roadmap
- Repository: https://github.com/hard-sign-hackaton/employer_first_roadmap

## Overview

Это MAX-бот профориентации и поступления для школьников, дополненный HTTP API для администраторов и работодателей. Основной путь проходит от выбора интересов и компании через проверку карьерного направления и экзаменов к созданию и выполнению roadmap: поступлению, практике/стажировке и заявке на работу. Внутренние слои — сервисы предметной логики и GORM-репозитории; PostgreSQL хранит каталог и прогресс, а состояние активного диалога также ведётся в памяти. Отдельно показаны каталог, API, feedback и напоминания. Связи сценария частично основаны на README; unsampled реализацию не предполагаю.

Main entry points: [`main.go`](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/main.go) (События и команды), [`database/database.go`](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/database/database.go) (PostgreSQL), [`services/trajectory_service_impl.go`](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/services/trajectory_service_impl.go) (Проверка траектории), [`repositories/gorm_roadmap_repository.go`](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/repositories/gorm_roadmap_repository.go) (Хранилище roadmap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Диалог MAX"]
  node_bot_entry["События и команды<br/>[main.go]"]
  node_message_router["Маршрутизация сообщений"]
  node_survey_entry["Опросы<br/>[small_survey.go]"]
  node_small_flow["Быстрый опрос"]
  node_big_flow["Выбор направления<br/>[big_survey_flow.go]"]
  node_dialog_state["Состояние диалога"]
end

subgraph group_career["Профориентация"]
  node_profile_service["Профиль"]
  node_trajectory["Проверка траектории"]
end

subgraph group_roadmap["Поступление и roadmap"]
  node_admission["Подбор поступления"]
  node_roadmap_flow["Шаги roadmap<br/>[roadmap_flow.go]"]
  node_roadmap_service["Управление roadmap"]
  node_roadmap_model["Roadmap и прогресс<br/>[roadmap.go]"]
end

subgraph group_data["Данные и каталог"]
  node_career_repo["Карьерный каталог"]
  node_education_repo["Каталог образования"]
  node_profile_repo["Профили"]
  node_roadmap_repo["Хранилище roadmap"]
  node_reference_repo["Справочники"]
  node_catalog_seed["Основной каталог<br/>[main_catalog.go]"]
  node_reference_seed["Справочные данные<br/>[seed.go]"]
  node_database[("PostgreSQL<br/>[database.go]")]
end

subgraph group_operations["API и напоминания"]
  node_employer_api["REST API и роли<br/>[handler.go]"]
  node_api_store["API-хранилище<br/>[store.go]"]
  node_reminder_service["Напоминания<br/>[service.go]"]
  node_reminder_scheduler["Планировщик<br/>[scheduler.go]"]
  node_max_sender["MAX-доставка<br/>[max_sender.go]"]
end

node_student(("Школьник"))
node_max(("MAX Bot API"))
node_api_actor(("Администратор / работодатель"))

node_student -->|"пишет боту"| node_max
node_max -->|"передаёт события"| node_bot_entry
node_bot_entry -->|"обрабатывает сообщения"| node_message_router
node_bot_entry -->|"регистрирует команды"| node_survey_entry
node_survey_entry -.->|"запускает опрос"| node_small_flow
node_message_router -.->|"обрабатывает диалог"| node_big_flow
node_small_flow -->|"хранит состояние"| node_dialog_state
node_big_flow -->|"хранит состояние"| node_dialog_state
node_bot_entry -->|"настраивает сервис"| node_profile_service
node_bot_entry -->|"настраивает сервис"| node_trajectory
node_bot_entry -->|"настраивает сервис"| node_admission
node_bot_entry -->|"настраивает сервис"| node_roadmap_service
node_trajectory -->|"читает направления"| node_career_repo
node_trajectory -->|"проверяет экзамены"| node_education_repo
node_trajectory -.->|"читает профиль"| node_profile_repo
node_trajectory -->|"создаёт цель"| node_roadmap_repo
node_profile_service -.->|"сохраняет профиль"| node_profile_repo
node_big_flow -->|"запрашивает оценку"| node_trajectory
node_roadmap_flow -->|"подбирает программы"| node_admission
node_roadmap_flow -->|"ведёт шаги"| node_roadmap_service
node_admission -.->|"ищет программы"| node_education_repo
node_admission -.->|"читает результаты"| node_profile_repo
node_admission -.->|"сохраняет план"| node_roadmap_repo
node_roadmap_service -->|"читает и обновляет"| node_roadmap_repo
node_roadmap_repo -->|"сохраняет состояние"| node_roadmap_model
node_career_repo -.->|"читает и пишет"| node_database
node_education_repo -->|"читает и пишет"| node_database
node_profile_repo -.->|"читает и пишет"| node_database
node_roadmap_repo -->|"читает и пишет"| node_database
node_reference_repo -.->|"читает справочники"| node_database
node_catalog_seed -->|"заполняет каталог"| node_database
node_reference_seed -->|"заполняет справочники"| node_database
node_api_actor -->|"вызывает REST API"| node_employer_api
node_employer_api -->|"обрабатывает запросы"| node_api_store
node_api_store -->|"читает и пишет"| node_database
node_employer_api -->|"отправляет feedback"| node_max_sender
node_reminder_scheduler -.->|"запускает отправку"| node_reminder_service
node_reminder_service -->|"читает активные пути"| node_roadmap_repo
node_reminder_service -->|"доставляет напоминания"| node_max_sender
node_max_sender -->|"отправляет push"| node_max

click node_bot_entry "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/main.go"
click node_message_router "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/handlers/message_listener.go"
click node_survey_entry "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/handlers/small_survey.go"
click node_small_flow "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/handlers/small_survey_flow.go"
click node_big_flow "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/handlers/big_survey_flow.go"
click node_dialog_state "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/utils/user_state_storage.go"
click node_profile_service "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/services/profile_service_impl.go"
click node_trajectory "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/services/trajectory_service_impl.go"
click node_admission "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/services/admission_service_impl.go"
click node_roadmap_flow "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/handlers/roadmap_flow.go"
click node_roadmap_service "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/services/roadmap_service_impl.go"
click node_roadmap_model "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/models/roadmap.go"
click node_career_repo "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/repositories/gorm_career_repository.go"
click node_education_repo "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/repositories/gorm_education_repository.go"
click node_profile_repo "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/repositories/gorm_profile_repository.go"
click node_roadmap_repo "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/repositories/gorm_roadmap_repository.go"
click node_reference_repo "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/repositories/gorm_reference_repository.go"
click node_catalog_seed "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/database/main_catalog.go"
click node_reference_seed "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/database/seed.go"
click node_database "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/database/database.go"
click node_employer_api "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/employerapi/handler.go"
click node_api_store "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/employerapi/store.go"
click node_reminder_service "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/reminders/service.go"
click node_reminder_scheduler "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/reminders/scheduler.go"
click node_max_sender "https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/reminders/max_sender.go"

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_bot_entry,node_message_router,node_survey_entry,node_small_flow,node_big_flow,node_dialog_state toneBlue
class node_profile_service,node_trajectory toneAmber
class node_admission,node_roadmap_flow,node_roadmap_service,node_roadmap_model,node_max toneMint
class node_career_repo,node_education_repo,node_profile_repo,node_roadmap_repo,node_reference_repo,node_catalog_seed,node_reference_seed,node_database toneRose
class node_employer_api,node_api_store,node_reminder_service,node_reminder_scheduler,node_max_sender,node_student,node_api_actor toneIndigo
```

## Components

### Диалог MAX

- [События и команды](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/main.go): `main.go`
- [Маршрутизация сообщений](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/handlers/message_listener.go): `handlers/message_listener.go`
- [Опросы](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/handlers/small_survey.go): `handlers/small_survey.go`
- [Быстрый опрос](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/handlers/small_survey_flow.go): `handlers/small_survey_flow.go`
- [Выбор направления](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/handlers/big_survey_flow.go): `handlers/big_survey_flow.go`
- [Состояние диалога](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/utils/user_state_storage.go): `utils/user_state_storage.go`

### Профориентация

- [Профиль](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/services/profile_service_impl.go): `services/profile_service_impl.go`
- [Проверка траектории](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/services/trajectory_service_impl.go): `services/trajectory_service_impl.go`

### Поступление и roadmap

- [Подбор поступления](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/services/admission_service_impl.go): `services/admission_service_impl.go`
- [Шаги roadmap](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/handlers/roadmap_flow.go): `handlers/roadmap_flow.go`
- [Управление roadmap](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/services/roadmap_service_impl.go): `services/roadmap_service_impl.go`
- [Roadmap и прогресс](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/models/roadmap.go): `models/roadmap.go`

### Данные и каталог

- [Карьерный каталог](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/repositories/gorm_career_repository.go): `repositories/gorm_career_repository.go`
- [Каталог образования](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/repositories/gorm_education_repository.go): `repositories/gorm_education_repository.go`
- [Профили](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/repositories/gorm_profile_repository.go): `repositories/gorm_profile_repository.go`
- [Хранилище roadmap](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/repositories/gorm_roadmap_repository.go): `repositories/gorm_roadmap_repository.go`
- [Справочники](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/repositories/gorm_reference_repository.go): `repositories/gorm_reference_repository.go`
- [Основной каталог](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/database/main_catalog.go): `database/main_catalog.go`
- [Справочные данные](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/database/seed.go): `database/seed.go`
- [PostgreSQL](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/database/database.go): `database/database.go`

### API и напоминания

- [REST API и роли](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/employerapi/handler.go): `employerapi/handler.go`
- [API-хранилище](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/employerapi/store.go): `employerapi/store.go`
- [Напоминания](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/reminders/service.go): `reminders/service.go`
- [Планировщик](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/reminders/scheduler.go): `reminders/scheduler.go`
- [MAX-доставка](https://github.com/hard-sign-hackaton/employer_first_roadmap/blob/main/reminders/max_sender.go): `reminders/max_sender.go`

### Other components

- **Школьник**
- **MAX Bot API**
- **Администратор / работодатель**

## Connections

- Школьник → MAX Bot API: пишет боту
- MAX Bot API → События и команды: передаёт события (evidence: `main.go`)
- События и команды → Маршрутизация сообщений: обрабатывает сообщения (evidence: `main.go`)
- События и команды → Опросы: регистрирует команды (evidence: `main.go`)
- Опросы → Быстрый опрос: запускает опрос
- Маршрутизация сообщений → Выбор направления: обрабатывает диалог
- Быстрый опрос → Состояние диалога: хранит состояние
- Выбор направления → Состояние диалога: хранит состояние
- События и команды → Профиль: настраивает сервис (evidence: `main.go`)
- События и команды → Проверка траектории: настраивает сервис (evidence: `main.go`)
- События и команды → Подбор поступления: настраивает сервис (evidence: `main.go`)
- События и команды → Управление roadmap: настраивает сервис (evidence: `main.go`)
- Проверка траектории → Карьерный каталог: читает направления (evidence: `services/trajectory_service_impl.go`)
- Проверка траектории → Каталог образования: проверяет экзамены (evidence: `services/trajectory_service_impl.go`)
- Проверка траектории → Профили: читает профиль
- Проверка траектории → Хранилище roadmap: создаёт цель (evidence: `services/trajectory_service_impl.go`)
- Профиль → Профили: сохраняет профиль
- Выбор направления → Проверка траектории: запрашивает оценку
- Шаги roadmap → Подбор поступления: подбирает программы
- Шаги roadmap → Управление roadmap: ведёт шаги
- Подбор поступления → Каталог образования: ищет программы
- Подбор поступления → Профили: читает результаты
- Подбор поступления → Хранилище roadmap: сохраняет план
- Управление roadmap → Хранилище roadmap: читает и обновляет (evidence: `services/roadmap_service_impl.go`)
- Хранилище roadmap → Roadmap и прогресс: сохраняет состояние (evidence: `repositories/gorm_roadmap_repository.go`)
- Карьерный каталог → PostgreSQL: читает и пишет
- Каталог образования → PostgreSQL: читает и пишет (evidence: `repositories/gorm_education_repository.go`)
- Профили → PostgreSQL: читает и пишет
- Хранилище roadmap → PostgreSQL: читает и пишет (evidence: `repositories/gorm_roadmap_repository.go`)
- Справочники → PostgreSQL: читает справочники
- Основной каталог → PostgreSQL: заполняет каталог
- Справочные данные → PostgreSQL: заполняет справочники
- Администратор / работодатель → REST API и роли: вызывает REST API
- REST API и роли → API-хранилище: обрабатывает запросы (evidence: `employerapi/handler.go`)
- API-хранилище → PostgreSQL: читает и пишет
- REST API и роли → MAX-доставка: отправляет feedback (evidence: `employerapi/handler.go`)
- Планировщик → Напоминания: запускает отправку
- Напоминания → Хранилище roadmap: читает активные пути
- Напоминания → MAX-доставка: доставляет напоминания (evidence: `reminders/service.go`)
- MAX-доставка → MAX Bot API: отправляет push
