# interact-club-of-bishkek/interact-backend architecture

> Architecture diagram of the GitHub repository interact-club-of-bishkek/interact-backend, 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/interact-club-of-bishkek/interact-backend
- Repository: https://github.com/interact-club-of-bishkek/interact-backend

## Overview

Interact Club Backend supports volunteer applications, club administration, teams and projects, with a Telegram bot offering application flows and group games. The main web flow is an applicant or administrator using Django/DRF endpoints to submit or manage volunteer records; teams and projects are separate domain capabilities, and Finik handles project-payment operations. The bot runner registers application, volunteer, project-creation, and game routers. Relationships are limited to README statements and indexed or excerpted references; unsampled web routes and model persistence details are not inferred.

Main entry points: [`users/views.py`](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/users/views.py) (Volunteer API), [`telegram_bot/bot_runner.py`](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/bot_runner.py) (Bot runner), [`interact/urls.py`](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/interact/urls.py) (API routing), [`projects/models.py`](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/projects/models.py) (Project records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web API"]
  node_api_routes["API routing<br/>[urls.py]"]
  node_volunteer_api["Volunteer API<br/>[views.py]"]
  node_serializers["Volunteer serialization<br/>[serializers.py]"]
end

subgraph group_club["Club management"]
  node_volunteer_records[("Volunteer records<br/>[models.py]")]
  node_commands_api["Command management<br/>[views.py]"]
  node_command_records[("Command records<br/>[models.py]")]
  node_projects_api["Project management<br/>[views.py]"]
  node_project_records[("Project records<br/>[models.py]")]
end

subgraph group_payments["Payments"]
  node_payment_api["Finik payment API<br/>[views.py]"]
  node_payment_records[("Payment records<br/>[models.py]")]
  node_finik_service["Finik service"]
end

subgraph group_bot["Telegram bot"]
  node_application_bot["Application flow"]
  node_bot_runner["Bot runner<br/>[bot_runner.py]"]
  node_general_handlers["General handlers<br/>[handlers.py]"]
  node_auth_check["Volunteer auth check<br/>[auth_check.py]"]
  node_project_bot["Project creation flow"]
end

subgraph group_games["Bot games"]
  node_crocodile_handlers["Crocodile handlers"]
  node_crocodile_game["Crocodile game logic<br/>[crocodile_game.py]"]
  node_mafia_handlers["Mafia handlers<br/>[handlers.py]"]
  node_mafia_game["Mafia game logic<br/>[game.py]"]
  node_mafia_storage[("Mafia game storage<br/>[storage.py]")]
end

node_applicant(("Applicant"))
node_admin_user(("Club administrator"))
node_telegram(("Telegram users"))
node_postgres[("PostgreSQL")]

node_applicant -.->|"uses API"| node_api_routes
node_admin_user -.->|"uses API"| node_api_routes
node_api_routes -->|"routes to"| node_volunteer_api
node_volunteer_api -->|"reads and writes"| node_volunteer_records
node_volunteer_api -->|"serializes"| node_serializers
node_volunteer_api -->|"uses command"| node_command_records
node_volunteer_api -->|"uses project"| node_project_records
node_admin_user -.->|"manages teams"| node_commands_api
node_commands_api -->|"reads and writes"| node_command_records
node_admin_user -.->|"manages projects"| node_projects_api
node_projects_api -->|"reads and writes"| node_project_records
node_api_routes -.->|"routes to"| node_projects_api
node_payment_api -->|"reads and writes"| node_payment_records
node_payment_api -->|"reads project"| node_project_records
node_payment_api -->|"sends requests"| node_finik_service
node_telegram -.->|"interacts with"| node_bot_runner
node_bot_runner -->|"registers router"| node_application_bot
node_bot_runner -->|"registers router"| node_project_bot
node_bot_runner -->|"registers router"| node_general_handlers
node_bot_runner -->|"registers router"| node_crocodile_handlers
node_bot_runner -->|"registers router"| node_mafia_handlers
node_application_bot -.->|"submits application"| node_volunteer_api
node_general_handlers -->|"checks password"| node_auth_check
node_auth_check -->|"posts credentials"| node_volunteer_api
node_crocodile_handlers -->|"starts rounds"| node_crocodile_game
node_mafia_handlers -->|"runs game logic"| node_mafia_game
node_mafia_handlers -->|"loads and saves"| node_mafia_storage
node_mafia_storage -->|"recreates game"| node_mafia_game
node_volunteer_records -.->|"persists in"| node_postgres
node_command_records -.->|"persists in"| node_postgres
node_project_records -.->|"persists in"| node_postgres

click node_api_routes "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/interact/urls.py"
click node_volunteer_api "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/users/views.py"
click node_application_bot "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/volunteers/telegram_handlers.py"
click node_volunteer_records "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/users/models.py"
click node_serializers "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/users/serializers.py"
click node_commands_api "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/commands/views.py"
click node_command_records "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/commands/models.py"
click node_projects_api "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/projects/views.py"
click node_project_records "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/projects/models.py"
click node_payment_api "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/finik/views.py"
click node_payment_records "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/finik/models.py"
click node_bot_runner "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/bot_runner.py"
click node_general_handlers "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/general/handlers.py"
click node_auth_check "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/volunteers/auth_check.py"
click node_project_bot "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/volunteers/project_creation.py"
click node_crocodile_handlers "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/crocodile/crocodile_runner.py"
click node_crocodile_game "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/crocodile/crocodile_game.py"
click node_mafia_handlers "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/mafia/handlers.py"
click node_mafia_game "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/mafia/game.py"
click node_mafia_storage "https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/mafia/storage.py"

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_api_routes,node_volunteer_api,node_serializers,node_telegram toneBlue
class node_volunteer_records,node_commands_api,node_command_records,node_projects_api,node_project_records,node_postgres toneAmber
class node_payment_api,node_payment_records,node_finik_service toneMint
class node_application_bot,node_bot_runner,node_general_handlers,node_auth_check,node_project_bot toneRose
class node_crocodile_handlers,node_crocodile_game,node_mafia_handlers,node_mafia_game,node_mafia_storage,node_applicant,node_admin_user toneIndigo
```

## Components

### Web API

- [API routing](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/interact/urls.py): `interact/urls.py`
- [Volunteer API](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/users/views.py): `users/views.py`
- [Volunteer serialization](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/users/serializers.py): `users/serializers.py`

### Club management

- [Volunteer records](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/users/models.py): `users/models.py`
- [Command management](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/commands/views.py): `commands/views.py`
- [Command records](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/commands/models.py): `commands/models.py`
- [Project management](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/projects/views.py): `projects/views.py`
- [Project records](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/projects/models.py): `projects/models.py`

### Payments

- [Finik payment API](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/finik/views.py): `finik/views.py`
- [Payment records](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/finik/models.py): `finik/models.py`
- **Finik service**

### Telegram bot

- [Application flow](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/volunteers/telegram_handlers.py): `telegram_bot/volunteers/telegram_handlers.py`
- [Bot runner](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/bot_runner.py): `telegram_bot/bot_runner.py`
- [General handlers](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/general/handlers.py): `telegram_bot/general/handlers.py`
- [Volunteer auth check](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/volunteers/auth_check.py): `telegram_bot/volunteers/auth_check.py`
- [Project creation flow](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/volunteers/project_creation.py): `telegram_bot/volunteers/project_creation.py`

### Bot games

- [Crocodile handlers](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/crocodile/crocodile_runner.py): `telegram_bot/crocodile/crocodile_runner.py`
- [Crocodile game logic](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/crocodile/crocodile_game.py): `telegram_bot/crocodile/crocodile_game.py`
- [Mafia handlers](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/mafia/handlers.py): `telegram_bot/mafia/handlers.py`
- [Mafia game logic](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/mafia/game.py): `telegram_bot/mafia/game.py`
- [Mafia game storage](https://github.com/interact-club-of-bishkek/interact-backend/blob/main/telegram_bot/mafia/storage.py): `telegram_bot/mafia/storage.py`

### Other components

- **Applicant**
- **Club administrator**
- **Telegram users**
- **PostgreSQL**

## Connections

- Applicant → API routing: uses API
- Club administrator → API routing: uses API
- API routing → Volunteer API: routes to (evidence: `interact/urls.py`)
- Volunteer API → Volunteer records: reads and writes (evidence: `users/views.py`)
- Volunteer API → Volunteer serialization: serializes (evidence: `users/views.py`)
- Volunteer API → Command records: uses command (evidence: `users/views.py`)
- Volunteer API → Project records: uses project (evidence: `users/views.py`)
- Club administrator → Command management: manages teams
- Command management → Command records: reads and writes (evidence: `commands/views.py`)
- Club administrator → Project management: manages projects
- Project management → Project records: reads and writes (evidence: `projects/views.py`)
- API routing → Project management: routes to
- Finik payment API → Payment records: reads and writes (evidence: `finik/views.py`)
- Finik payment API → Project records: reads project (evidence: `finik/views.py`)
- Finik payment API → Finik service: sends requests (evidence: `finik/views.py`)
- Telegram users → Bot runner: interacts with
- Bot runner → Application flow: registers router (evidence: `telegram_bot/bot_runner.py`)
- Bot runner → Project creation flow: registers router (evidence: `telegram_bot/bot_runner.py`)
- Bot runner → General handlers: registers router (evidence: `telegram_bot/bot_runner.py`)
- Bot runner → Crocodile handlers: registers router (evidence: `telegram_bot/bot_runner.py`)
- Bot runner → Mafia handlers: registers router (evidence: `telegram_bot/bot_runner.py`)
- Application flow → Volunteer API: submits application (evidence: `telegram_bot/volunteers/telegram_handlers.py`)
- General handlers → Volunteer auth check: checks password (evidence: `telegram_bot/general/handlers.py`)
- Volunteer auth check → Volunteer API: posts credentials (evidence: `telegram_bot/volunteers/auth_check.py`)
- Crocodile handlers → Crocodile game logic: starts rounds (evidence: `telegram_bot/crocodile/crocodile_runner.py`)
- Mafia handlers → Mafia game logic: runs game logic (evidence: `telegram_bot/mafia/handlers.py`)
- Mafia handlers → Mafia game storage: loads and saves (evidence: `telegram_bot/mafia/handlers.py`)
- Mafia game storage → Mafia game logic: recreates game (evidence: `telegram_bot/mafia/storage.py`)
- Volunteer records → PostgreSQL: persists in
- Command records → PostgreSQL: persists in
- Project records → PostgreSQL: persists in
