# 0himera/fsp-platform architecture

> Architecture diagram of the GitHub repository 0himera/fsp-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0himera/fsp-platform
- Repository: https://github.com/0himera/fsp-platform

## Overview

Арена ФСП Дагестана — платформа управления спортивным программированием: аккаунты спортсменов, соревнования, командные заявки, публикация протоколов и рейтинг. Основной путь — спортсмен регистрируется и подаёт заявку, организатор управляет соревнованием и командами, затем публикует результаты, которые появляются в истории выступлений и влияют на рейтинг. Отдельный контестный путь поддерживает ручную оценку алгоритмических решений и проверку CSV worker-ом. Граф объединяет документированные возможности с архитектурой из sampled-файлов; связи ненаблюдавшихся обработчиков показаны только на уровне, подтверждённом README.

Main entry points: [`backend/internal/httpapi/server.go`](https://github.com/0himera/fsp-platform/blob/main/backend/internal/httpapi/server.go) (HTTP API), [`frontend/src/shared/api/client.ts`](https://github.com/0himera/fsp-platform/blob/main/frontend/src/shared/api/client.ts) (API client), [`backend/internal/platform/database.go`](https://github.com/0himera/fsp-platform/blob/main/backend/internal/platform/database.go) (PostgreSQL), [`frontend/src/app`](https://github.com/0himera/fsp-platform/tree/main/frontend/src/app) (Next.js интерфейс)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Интерфейс"]
  node_web["Next.js интерфейс"]
  node_api_client["API client<br/>[client.ts]"]
  node_profile_ui["Профили и рейтинг"]
  node_calendar_ui["Календарь"]
end

subgraph group_identity["Аккаунты"]
  node_auth_ui["Email auth"]
  node_auth_api["Auth API"]
  node_mailer["Почта<br/>[smtp.go]"]
end

subgraph group_events["Соревнования"]
  node_competition_ui["Карточка соревнования"]
  node_team_ui["Управление командами"]
  node_competition_api["HTTP API<br/>[server.go]"]
  node_competition_service["Соревнования и заявки<br/>[service.go]"]
  node_codeforces["Codeforces"]
end

subgraph group_contests["Контесты"]
  node_contest_ui["Контестный интерфейс"]
  node_contest_api["Контестные API-маршруты<br/>[contest.go]"]
  node_contest_engine["Contest Engine<br/>[main.go]"]
  node_contest_service["Контестная логика<br/>[service.go]"]
  node_contest_worker["CSV worker<br/>[main.go]"]
end

subgraph group_platform["Платформенные данные"]
  node_rating["Рейтинг<br/>[rating.go]"]
  node_database[("PostgreSQL<br/>[database.go]")]
  node_ai["AI-сервис<br/>[service.go]"]
end

node_athlete(("Спортсмен"))
node_organizer(("Организатор"))
node_gemini{{"Gemini API"}}
node_email_service{{"SMTP-сервис"}}
node_external_platform(("Внешняя площадка"))

node_athlete -->|"работает"| node_web
node_organizer -->|"управляет"| node_web
node_web -->|"использует"| node_auth_ui
node_web -->|"показывает"| node_competition_ui
node_web -->|"показывает"| node_calendar_ui
node_web -->|"показывает"| node_profile_ui
node_auth_ui -->|"отправляет запросы"| node_api_client
node_competition_ui -->|"отправляет запросы"| node_api_client
node_team_ui -->|"отправляет запросы"| node_api_client
node_contest_ui -->|"отправляет запросы"| node_api_client
node_profile_ui -->|"запрашивает данные"| node_api_client
node_calendar_ui -->|"запрашивает данные"| node_api_client
node_api_client -->|"HTTP запросы"| node_competition_api
node_competition_api -->|"обрабатывает auth"| node_auth_api
node_competition_api -->|"обрабатывает соревнования"| node_competition_service
node_competition_api -->|"обрабатывает контесты"| node_contest_api
node_auth_api -->|"читает и пишет"| node_database
node_auth_api -->|"отправляет письма"| node_mailer
node_mailer -.->|"SMTP"| node_email_service
node_competition_service -->|"читает и пишет"| node_database
node_competition_service -->|"публикация пересчитывает"| node_rating
node_rating -->|"читает и пишет"| node_database
node_competition_api -->|"обрабатывает интеграцию"| node_codeforces
node_codeforces -->|"читает и пишет"| node_database
node_competition_api -->|"обрабатывает AI-запросы"| node_ai
node_ai -->|"читает и пишет"| node_database
node_ai -.->|"запрашивает генерацию"| node_gemini
node_contest_api -->|"проксирует запросы"| node_contest_engine
node_contest_engine -->|"вызывает сервис"| node_contest_service
node_contest_service -->|"хранит контесты и очередь"| node_database
node_contest_worker -->|"обрабатывает задания"| node_contest_service
node_contest_worker -->|"читает очередь"| node_database
node_contest_engine -->|"передаёт итоги"| node_competition_api
node_external_platform -.->|"запрашивает export"| node_competition_api

click node_web "https://github.com/0himera/fsp-platform/tree/main/frontend/src/app"
click node_api_client "https://github.com/0himera/fsp-platform/blob/main/frontend/src/shared/api/client.ts"
click node_auth_ui "https://github.com/0himera/fsp-platform/tree/main/frontend/src/features/auth-by-email"
click node_auth_api "https://github.com/0himera/fsp-platform/tree/main/backend/internal/auth"
click node_mailer "https://github.com/0himera/fsp-platform/blob/main/backend/internal/mailer/smtp.go"
click node_competition_ui "https://github.com/0himera/fsp-platform/tree/main/frontend/src/views/competition-detail"
click node_team_ui "https://github.com/0himera/fsp-platform/tree/main/frontend/src/features/manage-teams"
click node_competition_api "https://github.com/0himera/fsp-platform/blob/main/backend/internal/httpapi/server.go"
click node_competition_service "https://github.com/0himera/fsp-platform/blob/main/backend/internal/competitions/service.go"
click node_rating "https://github.com/0himera/fsp-platform/blob/main/backend/internal/rating/rating.go"
click node_profile_ui "https://github.com/0himera/fsp-platform/tree/main/frontend/src/views/athlete-profile"
click node_calendar_ui "https://github.com/0himera/fsp-platform/tree/main/frontend/src/views/calendar"
click node_contest_ui "https://github.com/0himera/fsp-platform/tree/main/frontend/src/views/contest-solve"
click node_contest_api "https://github.com/0himera/fsp-platform/blob/main/backend/internal/httpapi/contest.go"
click node_contest_engine "https://github.com/0himera/fsp-platform/blob/main/backend/cmd/contest-engine/main.go"
click node_contest_service "https://github.com/0himera/fsp-platform/blob/main/backend/internal/contest/service.go"
click node_contest_worker "https://github.com/0himera/fsp-platform/blob/main/backend/cmd/contest-worker/main.go"
click node_database "https://github.com/0himera/fsp-platform/blob/main/backend/internal/platform/database.go"
click node_codeforces "https://github.com/0himera/fsp-platform/tree/main/backend/internal/codeforces"
click node_ai "https://github.com/0himera/fsp-platform/blob/main/backend/internal/ai/service.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_web,node_api_client,node_profile_ui,node_calendar_ui toneBlue
class node_auth_ui,node_auth_api,node_mailer toneAmber
class node_competition_ui,node_team_ui,node_competition_api,node_competition_service,node_codeforces,node_gemini toneMint
class node_contest_ui,node_contest_api,node_contest_engine,node_contest_service,node_contest_worker toneRose
class node_rating,node_database,node_ai,node_athlete,node_organizer,node_email_service,node_external_platform toneIndigo
```

## Components

### Интерфейс

- [Next.js интерфейс](https://github.com/0himera/fsp-platform/tree/main/frontend/src/app): `frontend/src/app`
- [API client](https://github.com/0himera/fsp-platform/blob/main/frontend/src/shared/api/client.ts): `frontend/src/shared/api/client.ts`
- [Профили и рейтинг](https://github.com/0himera/fsp-platform/tree/main/frontend/src/views/athlete-profile): `frontend/src/views/athlete-profile`
- [Календарь](https://github.com/0himera/fsp-platform/tree/main/frontend/src/views/calendar): `frontend/src/views/calendar`

### Аккаунты

- [Email auth](https://github.com/0himera/fsp-platform/tree/main/frontend/src/features/auth-by-email): `frontend/src/features/auth-by-email`
- [Auth API](https://github.com/0himera/fsp-platform/tree/main/backend/internal/auth): `backend/internal/auth`
- [Почта](https://github.com/0himera/fsp-platform/blob/main/backend/internal/mailer/smtp.go): `backend/internal/mailer/smtp.go`

### Соревнования

- [Карточка соревнования](https://github.com/0himera/fsp-platform/tree/main/frontend/src/views/competition-detail): `frontend/src/views/competition-detail`
- [Управление командами](https://github.com/0himera/fsp-platform/tree/main/frontend/src/features/manage-teams): `frontend/src/features/manage-teams`
- [HTTP API](https://github.com/0himera/fsp-platform/blob/main/backend/internal/httpapi/server.go): `backend/internal/httpapi/server.go`
- [Соревнования и заявки](https://github.com/0himera/fsp-platform/blob/main/backend/internal/competitions/service.go): `backend/internal/competitions/service.go`
- [Codeforces](https://github.com/0himera/fsp-platform/tree/main/backend/internal/codeforces): `backend/internal/codeforces`

### Контесты

- [Контестный интерфейс](https://github.com/0himera/fsp-platform/tree/main/frontend/src/views/contest-solve): `frontend/src/views/contest-solve`
- [Контестные API-маршруты](https://github.com/0himera/fsp-platform/blob/main/backend/internal/httpapi/contest.go): `backend/internal/httpapi/contest.go`
- [Contest Engine](https://github.com/0himera/fsp-platform/blob/main/backend/cmd/contest-engine/main.go): `backend/cmd/contest-engine/main.go`
- [Контестная логика](https://github.com/0himera/fsp-platform/blob/main/backend/internal/contest/service.go): `backend/internal/contest/service.go`
- [CSV worker](https://github.com/0himera/fsp-platform/blob/main/backend/cmd/contest-worker/main.go): `backend/cmd/contest-worker/main.go`

### Платформенные данные

- [Рейтинг](https://github.com/0himera/fsp-platform/blob/main/backend/internal/rating/rating.go): `backend/internal/rating/rating.go`
- [PostgreSQL](https://github.com/0himera/fsp-platform/blob/main/backend/internal/platform/database.go): `backend/internal/platform/database.go`
- [AI-сервис](https://github.com/0himera/fsp-platform/blob/main/backend/internal/ai/service.go): `backend/internal/ai/service.go`

### Other components

- **Спортсмен**
- **Организатор**
- **Gemini API**
- **SMTP-сервис**
- **Внешняя площадка**

## Connections

- Спортсмен → Next.js интерфейс: работает
- Организатор → Next.js интерфейс: управляет
- Next.js интерфейс → Email auth: использует
- Next.js интерфейс → Карточка соревнования: показывает
- Next.js интерфейс → Календарь: показывает
- Next.js интерфейс → Профили и рейтинг: показывает
- Email auth → API client: отправляет запросы
- Карточка соревнования → API client: отправляет запросы
- Управление командами → API client: отправляет запросы
- Контестный интерфейс → API client: отправляет запросы
- Профили и рейтинг → API client: запрашивает данные
- Календарь → API client: запрашивает данные
- API client → HTTP API: HTTP запросы
- HTTP API → Auth API: обрабатывает auth
- HTTP API → Соревнования и заявки: обрабатывает соревнования
- HTTP API → Контестные API-маршруты: обрабатывает контесты
- Auth API → PostgreSQL: читает и пишет
- Auth API → Почта: отправляет письма
- Почта → SMTP-сервис: SMTP
- Соревнования и заявки → PostgreSQL: читает и пишет
- Соревнования и заявки → Рейтинг: публикация пересчитывает
- Рейтинг → PostgreSQL: читает и пишет
- HTTP API → Codeforces: обрабатывает интеграцию
- Codeforces → PostgreSQL: читает и пишет
- HTTP API → AI-сервис: обрабатывает AI-запросы
- AI-сервис → PostgreSQL: читает и пишет
- AI-сервис → Gemini API: запрашивает генерацию
- Контестные API-маршруты → Contest Engine: проксирует запросы
- Contest Engine → Контестная логика: вызывает сервис
- Контестная логика → PostgreSQL: хранит контесты и очередь
- CSV worker → Контестная логика: обрабатывает задания
- CSV worker → PostgreSQL: читает очередь
- Contest Engine → HTTP API: передаёт итоги
- Внешняя площадка → HTTP API: запрашивает export