# shmiklak/vitalina2222 architecture

> Architecture diagram of the GitHub repository shmiklak/vitalina2222, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shmiklak/vitalina2222
- Repository: https://github.com/shmiklak/vitalina2222

## Overview

Vitalina2222 is a Discord character bot: Discord users send messages or commands, the bot handles them and replies in the channel; in AI modes it obtains generated text from OpenAI. The code also supports osu! lookups and role verification, giveaways, and persistent user/message data. Groups separate Discord handling, AI and persona prompts, osu! features, and persistence. The Discord handler excerpt is partial, so some command-specific implementation details and links are not shown; the graph includes only relationships supported by the excerpts, source index, or README.

Main entry points: [`app/discord_bot/discord_api.py`](https://github.com/shmiklak/vitalina2222/blob/main/app/discord_bot/discord_api.py) (Event and command handler), [`app/chatgpt_ai/openai.py`](https://github.com/shmiklak/vitalina2222/blob/main/app/chatgpt_ai/openai.py) (Chat response generation), [`app/database/database.py`](https://github.com/shmiklak/vitalina2222/blob/main/app/database/database.py) (Database operations), [`app/vitalina_utilities/utilities.py`](https://github.com/shmiklak/vitalina2222/blob/main/app/vitalina_utilities/utilities.py) (Random content utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discord["Discord bot"]
  node_launcher["Bot launcher<br/>[run.py]"]
  node_handler["Event and command handler<br/>[discord_api.py]"]
  node_random_content["Random content utilities<br/>[utilities.py]"]
end

subgraph group_ai["AI persona"]
  node_openai_logic["Chat response generation<br/>[openai.py]"]
  node_persona["Character prompts<br/>[vitalina.txt]"]
end

subgraph group_osu["osu! features"]
  node_osu_api["osu! API access<br/>[api.py]"]
  node_score_embed["Score embed<br/>[Score.py]"]
  node_user_embed["User embed<br/>[User.py]"]
  node_beatmap_embed["Beatmap embed<br/>[Beatmap.py]"]
end

subgraph group_data["Persistence"]
  node_db_helpers["Database operations<br/>[database.py]"]
end

node_users(("Discord users"))
node_discord_platform{{"Discord"}}
node_openai_service{{"OpenAI API"}}
node_postgres[("PostgreSQL")]

node_users -->|"send messages"| node_discord_platform
node_discord_platform -->|"delivers events"| node_handler
node_launcher -->|"starts bot"| node_handler
node_handler -->|"sends replies"| node_discord_platform
node_handler -->|"requests replies"| node_openai_logic
node_openai_logic -->|"loads prompts"| node_persona
node_openai_logic -->|"requests completion"| node_openai_service
node_handler -->|"selects content"| node_random_content
node_handler -->|"requests osu! data"| node_osu_api
node_handler -->|"uses score view"| node_score_embed
node_handler -->|"uses user view"| node_user_embed
node_handler -->|"uses map view"| node_beatmap_embed
node_handler -->|"reads and writes"| node_db_helpers
node_db_helpers -->|"queries and updates"| node_postgres
node_db_helpers -->|"imports user selector"| node_random_content

click node_launcher "https://github.com/shmiklak/vitalina2222/blob/main/run.py"
click node_handler "https://github.com/shmiklak/vitalina2222/blob/main/app/discord_bot/discord_api.py"
click node_random_content "https://github.com/shmiklak/vitalina2222/blob/main/app/vitalina_utilities/utilities.py"
click node_openai_logic "https://github.com/shmiklak/vitalina2222/blob/main/app/chatgpt_ai/openai.py"
click node_persona "https://github.com/shmiklak/vitalina2222/blob/main/vitalina.txt"
click node_osu_api "https://github.com/shmiklak/vitalina2222/blob/main/app/osu/api.py"
click node_score_embed "https://github.com/shmiklak/vitalina2222/blob/main/app/responses/Score.py"
click node_user_embed "https://github.com/shmiklak/vitalina2222/blob/main/app/responses/User.py"
click node_beatmap_embed "https://github.com/shmiklak/vitalina2222/blob/main/app/responses/Beatmap.py"
click node_db_helpers "https://github.com/shmiklak/vitalina2222/blob/main/app/database/database.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_launcher,node_handler,node_random_content,node_users toneBlue
class node_openai_logic,node_persona,node_postgres toneAmber
class node_osu_api,node_score_embed,node_user_embed,node_beatmap_embed,node_openai_service toneMint
class node_db_helpers toneRose
class node_discord_platform toneIndigo
```

## Components

### Discord bot

- [Bot launcher](https://github.com/shmiklak/vitalina2222/blob/main/run.py): `run.py`
- [Event and command handler](https://github.com/shmiklak/vitalina2222/blob/main/app/discord_bot/discord_api.py): `app/discord_bot/discord_api.py`
- [Random content utilities](https://github.com/shmiklak/vitalina2222/blob/main/app/vitalina_utilities/utilities.py): `app/vitalina_utilities/utilities.py`

### AI persona

- [Chat response generation](https://github.com/shmiklak/vitalina2222/blob/main/app/chatgpt_ai/openai.py): `app/chatgpt_ai/openai.py`
- [Character prompts](https://github.com/shmiklak/vitalina2222/blob/main/vitalina.txt): `vitalina.txt`

### osu! features

- [osu! API access](https://github.com/shmiklak/vitalina2222/blob/main/app/osu/api.py): `app/osu/api.py`
- [Score embed](https://github.com/shmiklak/vitalina2222/blob/main/app/responses/Score.py): `app/responses/Score.py`
- [User embed](https://github.com/shmiklak/vitalina2222/blob/main/app/responses/User.py): `app/responses/User.py`
- [Beatmap embed](https://github.com/shmiklak/vitalina2222/blob/main/app/responses/Beatmap.py): `app/responses/Beatmap.py`

### Persistence

- [Database operations](https://github.com/shmiklak/vitalina2222/blob/main/app/database/database.py): `app/database/database.py`

### Other components

- **Discord users**
- **Discord**
- **OpenAI API**
- **PostgreSQL**

## Connections

- Discord users → Discord: send messages (evidence: `readme.md`)
- Discord → Event and command handler: delivers events (evidence: `app/discord_bot/discord_api.py`)
- Bot launcher → Event and command handler: starts bot (evidence: `run.py`)
- Event and command handler → Discord: sends replies (evidence: `app/discord_bot/discord_api.py`)
- Event and command handler → Chat response generation: requests replies (evidence: `app/discord_bot/discord_api.py`)
- Chat response generation → Character prompts: loads prompts (evidence: `app/chatgpt_ai/openai.py`)
- Chat response generation → OpenAI API: requests completion (evidence: `app/chatgpt_ai/openai.py`)
- Event and command handler → Random content utilities: selects content (evidence: `app/discord_bot/discord_api.py`)
- Event and command handler → osu! API access: requests osu! data (evidence: `app/discord_bot/discord_api.py`)
- Event and command handler → Score embed: uses score view (evidence: `app/discord_bot/discord_api.py`)
- Event and command handler → User embed: uses user view (evidence: `app/discord_bot/discord_api.py`)
- Event and command handler → Beatmap embed: uses map view (evidence: `app/discord_bot/discord_api.py`)
- Event and command handler → Database operations: reads and writes (evidence: `app/discord_bot/discord_api.py`)
- Database operations → PostgreSQL: queries and updates (evidence: `app/database/database.py`)
- Database operations → Random content utilities: imports user selector (evidence: `app/database/database.py`)
