# jishnuharis/anonchatzonebot architecture

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

- Interactive diagram: https://gitdiagram.com/jishnuharis/anonchatzonebot
- Repository: https://github.com/jishnuharis/anonchatzonebot

## Overview

AnonChatZoneBot is a Telegram anonymous-chat product. Users complete profile setup and interest preferences, request a partner, are filtered and paired, then exchange relayed messages until either ends the session; supporting branches include games, friends, subscriptions, and privacy features. The graph preserves the README’s major capabilities. Relationship evidence is limited to README statements and SOURCE INDEX references; unsampled modules are represented by their documented responsibilities, without claiming their internals were inspected.

Main entry points: [`session_manager.py`](https://github.com/jishnuharis/anonchatzonebot/blob/main/session_manager.py) (Session lifecycle), [`saveNload.py`](https://github.com/jishnuharis/anonchatzonebot/blob/main/saveNload.py) (PostgreSQL storage), [`matchmaking.py`](https://github.com/jishnuharis/anonchatzonebot/blob/main/matchmaking.py) (Matchmaking and filters), [`handlers/setup.py`](https://github.com/jishnuharis/anonchatzonebot/blob/main/handlers/setup.py) (Profile onboarding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_setup["Profile onboarding<br/>[setup.py]"]
  node_country["Country selection<br/>[country.py]"]
  node_preferences["Interest preferences<br/>[preferences.py]"]
  node_channel["Channel membership gate<br/>[channel_gate.py]"]
  node_rating["Post-chat rating<br/>[rating.py]"]
end

subgraph group_chat["Chat runtime"]
  node_find["Partner search command<br/>[find.py]"]
  node_matching["Matchmaking and filters<br/>[matchmaking.py]"]
  node_sessions["Session lifecycle<br/>[session_manager.py]"]
  node_relay["Message and action relay<br/>[relay.py]"]
  node_media["View-once media privacy<br/>[media_privacy.py]"]
  node_next["Skip and reconnect<br/>[next.py]"]
end

subgraph group_engagement["Engagement features"]
  node_friends["Anonymous friends<br/>[friends.py]"]
  node_game_requests["Game challenges<br/>[game_requests.py]"]
  node_game_registry["Active game registry<br/>[registry.py]"]
  node_games["Mini-game engines"]
  node_content["Game content loader<br/>[content_manager.py]"]
  node_transcript["Transcript export<br/>[transcript.py]"]
  node_promotions["Sponsor campaigns<br/>[service.py]"]
  node_referral["Referral rewards<br/>[referral.py]"]
  node_voice["Anonymous voice calls<br/>[call.py]"]
end

subgraph group_platform["Platform services"]
  node_main["Bot startup and routing<br/>[main.py]"]
  node_moderation["Reports and restrictions<br/>[moderation.py]"]
  node_payments["Payment handlers<br/>[payments.py]"]
  node_subscription["Subscription entitlements<br/>[subscription.py]"]
  node_security["API safety and rate limits<br/>[security.py]"]
  node_state["Shared runtime state<br/>[init.py]"]
  node_database[("PostgreSQL storage<br/>[saveNload.py]")]
  node_migrations["Schema and migration<br/>[migrations.py]"]
end

subgraph group_operations["Operations"]
  node_health["Health endpoint<br/>[app.py]"]
end

node_users(("Telegram users"))
node_telegram["Telegram API"]

node_users -->|"send commands"| node_telegram
node_telegram -->|"delivers updates"| node_main
node_main -->|"routes commands"| node_find
node_main -->|"routes handlers"| node_setup
node_setup -->|"requests selection"| node_country
node_setup -->|"captures referral"| node_referral
node_setup -->|"checks membership"| node_channel
node_preferences -->|"checks membership"| node_channel
node_users -->|"requests partner"| node_find
node_find -->|"queues for match"| node_matching
node_matching -->|"creates paired session"| node_sessions
node_matching -->|"filters restrictions"| node_moderation
node_sessions -->|"tracks active pairs"| node_state
node_sessions -->|"tears down games"| node_game_registry
node_sessions -->|"triggers post-chat delivery"| node_promotions
node_sessions -->|"starts post-chat rating"| node_rating
node_sessions -.->|"supports export"| node_transcript
node_users -->|"sends chat messages"| node_relay
node_relay -->|"forwards messages"| node_telegram
node_relay -->|"applies media privacy"| node_media
node_relay -->|"uses safe calls"| node_security
node_users -->|"skips partner"| node_next
node_next -->|"ends current session"| node_sessions
node_next -->|"requests another match"| node_matching
node_users -->|"manages friend list"| node_friends
node_friends -->|"checks busy state"| node_matching
node_friends -->|"reads friend records"| node_database
node_game_requests -->|"dispatches challenges"| node_games
node_games -->|"registers active game"| node_game_registry
node_games -->|"loads questions"| node_content
node_content -.->|"loads database content"| node_database
node_promotions -->|"reads campaign data"| node_database
node_referral -->|"grants rewards"| node_subscription
node_payments -->|"applies purchases"| node_subscription
node_subscription -->|"checks cached entitlements"| node_state
node_moderation -->|"persists restrictions"| node_database
node_state -->|"loads and flushes users"| node_database
node_migrations -->|"defines schema"| node_database
node_users -->|"starts voice call"| node_voice
node_voice -->|"launches WebApp room"| node_telegram
node_users -->|"requests health status"| node_health
node_health -.->|"uses bot metrics"| node_telegram

click node_main "https://github.com/jishnuharis/anonchatzonebot/blob/main/main.py"
click node_setup "https://github.com/jishnuharis/anonchatzonebot/blob/main/handlers/setup.py"
click node_country "https://github.com/jishnuharis/anonchatzonebot/blob/main/handlers/country.py"
click node_preferences "https://github.com/jishnuharis/anonchatzonebot/blob/main/handlers/preferences.py"
click node_channel "https://github.com/jishnuharis/anonchatzonebot/blob/main/channel_gate.py"
click node_find "https://github.com/jishnuharis/anonchatzonebot/blob/main/commands/find.py"
click node_matching "https://github.com/jishnuharis/anonchatzonebot/blob/main/matchmaking.py"
click node_sessions "https://github.com/jishnuharis/anonchatzonebot/blob/main/session_manager.py"
click node_relay "https://github.com/jishnuharis/anonchatzonebot/blob/main/relay.py"
click node_media "https://github.com/jishnuharis/anonchatzonebot/blob/main/media_privacy.py"
click node_next "https://github.com/jishnuharis/anonchatzonebot/blob/main/commands/next.py"
click node_moderation "https://github.com/jishnuharis/anonchatzonebot/blob/main/moderation.py"
click node_rating "https://github.com/jishnuharis/anonchatzonebot/blob/main/handlers/rating.py"
click node_friends "https://github.com/jishnuharis/anonchatzonebot/blob/main/handlers/friends.py"
click node_game_requests "https://github.com/jishnuharis/anonchatzonebot/blob/main/games/game_requests.py"
click node_game_registry "https://github.com/jishnuharis/anonchatzonebot/blob/main/games/registry.py"
click node_games "https://github.com/jishnuharis/anonchatzonebot/tree/main/games"
click node_content "https://github.com/jishnuharis/anonchatzonebot/blob/main/games/content/content_manager.py"
click node_transcript "https://github.com/jishnuharis/anonchatzonebot/blob/main/handlers/transcript.py"
click node_promotions "https://github.com/jishnuharis/anonchatzonebot/blob/main/promotions/service.py"
click node_referral "https://github.com/jishnuharis/anonchatzonebot/blob/main/referral.py"
click node_payments "https://github.com/jishnuharis/anonchatzonebot/blob/main/handlers/payments.py"
click node_subscription "https://github.com/jishnuharis/anonchatzonebot/blob/main/subscription.py"
click node_security "https://github.com/jishnuharis/anonchatzonebot/blob/main/security.py"
click node_state "https://github.com/jishnuharis/anonchatzonebot/blob/main/init.py"
click node_database "https://github.com/jishnuharis/anonchatzonebot/blob/main/saveNload.py"
click node_migrations "https://github.com/jishnuharis/anonchatzonebot/blob/main/migrations.py"
click node_health "https://github.com/jishnuharis/anonchatzonebot/blob/main/app.py"
click node_voice "https://github.com/jishnuharis/anonchatzonebot/blob/main/commands/call.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_setup,node_country,node_preferences,node_channel,node_rating,node_users toneBlue
class node_find,node_matching,node_sessions,node_relay,node_media,node_next toneAmber
class node_friends,node_game_requests,node_game_registry,node_games,node_content,node_transcript,node_promotions,node_referral,node_voice,node_telegram toneMint
class node_main,node_moderation,node_payments,node_subscription,node_security,node_state,node_database,node_migrations toneRose
class node_health toneIndigo
```

## Components

### User experience

- [Profile onboarding](https://github.com/jishnuharis/anonchatzonebot/blob/main/handlers/setup.py): `handlers/setup.py`
- [Country selection](https://github.com/jishnuharis/anonchatzonebot/blob/main/handlers/country.py): `handlers/country.py`
- [Interest preferences](https://github.com/jishnuharis/anonchatzonebot/blob/main/handlers/preferences.py): `handlers/preferences.py`
- [Channel membership gate](https://github.com/jishnuharis/anonchatzonebot/blob/main/channel_gate.py): `channel_gate.py`
- [Post-chat rating](https://github.com/jishnuharis/anonchatzonebot/blob/main/handlers/rating.py): `handlers/rating.py`

### Chat runtime

- [Partner search command](https://github.com/jishnuharis/anonchatzonebot/blob/main/commands/find.py): `commands/find.py`
- [Matchmaking and filters](https://github.com/jishnuharis/anonchatzonebot/blob/main/matchmaking.py): `matchmaking.py`
- [Session lifecycle](https://github.com/jishnuharis/anonchatzonebot/blob/main/session_manager.py): `session_manager.py`
- [Message and action relay](https://github.com/jishnuharis/anonchatzonebot/blob/main/relay.py): `relay.py`
- [View-once media privacy](https://github.com/jishnuharis/anonchatzonebot/blob/main/media_privacy.py): `media_privacy.py`
- [Skip and reconnect](https://github.com/jishnuharis/anonchatzonebot/blob/main/commands/next.py): `commands/next.py`

### Engagement features

- [Anonymous friends](https://github.com/jishnuharis/anonchatzonebot/blob/main/handlers/friends.py): `handlers/friends.py`
- [Game challenges](https://github.com/jishnuharis/anonchatzonebot/blob/main/games/game_requests.py): `games/game_requests.py`
- [Active game registry](https://github.com/jishnuharis/anonchatzonebot/blob/main/games/registry.py): `games/registry.py`
- [Mini-game engines](https://github.com/jishnuharis/anonchatzonebot/tree/main/games): `games`
- [Game content loader](https://github.com/jishnuharis/anonchatzonebot/blob/main/games/content/content_manager.py): `games/content/content_manager.py`
- [Transcript export](https://github.com/jishnuharis/anonchatzonebot/blob/main/handlers/transcript.py): `handlers/transcript.py`
- [Sponsor campaigns](https://github.com/jishnuharis/anonchatzonebot/blob/main/promotions/service.py): `promotions/service.py`
- [Referral rewards](https://github.com/jishnuharis/anonchatzonebot/blob/main/referral.py): `referral.py`
- [Anonymous voice calls](https://github.com/jishnuharis/anonchatzonebot/blob/main/commands/call.py): `commands/call.py`

### Platform services

- [Bot startup and routing](https://github.com/jishnuharis/anonchatzonebot/blob/main/main.py): `main.py`
- [Reports and restrictions](https://github.com/jishnuharis/anonchatzonebot/blob/main/moderation.py): `moderation.py`
- [Payment handlers](https://github.com/jishnuharis/anonchatzonebot/blob/main/handlers/payments.py): `handlers/payments.py`
- [Subscription entitlements](https://github.com/jishnuharis/anonchatzonebot/blob/main/subscription.py): `subscription.py`
- [API safety and rate limits](https://github.com/jishnuharis/anonchatzonebot/blob/main/security.py): `security.py`
- [Shared runtime state](https://github.com/jishnuharis/anonchatzonebot/blob/main/init.py): `init.py`
- [PostgreSQL storage](https://github.com/jishnuharis/anonchatzonebot/blob/main/saveNload.py): `saveNload.py`
- [Schema and migration](https://github.com/jishnuharis/anonchatzonebot/blob/main/migrations.py): `migrations.py`

### Operations

- [Health endpoint](https://github.com/jishnuharis/anonchatzonebot/blob/main/app.py): `app.py`

### Other components

- **Telegram users**
- **Telegram API**

## Connections

- Telegram users → Telegram API: send commands
- Telegram API → Bot startup and routing: delivers updates
- Bot startup and routing → Partner search command: routes commands (evidence: `main.py`)
- Bot startup and routing → Profile onboarding: routes handlers (evidence: `main.py`)
- Profile onboarding → Country selection: requests selection (evidence: `handlers/setup.py`)
- Profile onboarding → Referral rewards: captures referral (evidence: `handlers/setup.py`)
- Profile onboarding → Channel membership gate: checks membership (evidence: `handlers/setup.py`)
- Interest preferences → Channel membership gate: checks membership (evidence: `handlers/preferences.py`)
- Telegram users → Partner search command: requests partner
- Partner search command → Matchmaking and filters: queues for match
- Matchmaking and filters → Session lifecycle: creates paired session (evidence: `matchmaking.py`)
- Matchmaking and filters → Reports and restrictions: filters restrictions (evidence: `matchmaking.py`)
- Session lifecycle → Shared runtime state: tracks active pairs (evidence: `session_manager.py`)
- Session lifecycle → Active game registry: tears down games (evidence: `session_manager.py`)
- Session lifecycle → Sponsor campaigns: triggers post-chat delivery (evidence: `session_manager.py`)
- Session lifecycle → Post-chat rating: starts post-chat rating (evidence: `session_manager.py`)
- Session lifecycle → Transcript export: supports export
- Telegram users → Message and action relay: sends chat messages
- Message and action relay → Telegram API: forwards messages
- Message and action relay → View-once media privacy: applies media privacy (evidence: `relay.py`)
- Message and action relay → API safety and rate limits: uses safe calls (evidence: `relay.py`)
- Telegram users → Skip and reconnect: skips partner
- Skip and reconnect → Session lifecycle: ends current session (evidence: `commands/next.py`)
- Skip and reconnect → Matchmaking and filters: requests another match (evidence: `commands/next.py`)
- Telegram users → Anonymous friends: manages friend list
- Anonymous friends → Matchmaking and filters: checks busy state (evidence: `handlers/friends.py`)
- Anonymous friends → PostgreSQL storage: reads friend records (evidence: `handlers/friends.py`)
- Game challenges → Mini-game engines: dispatches challenges (evidence: `games/game_requests.py`)
- Mini-game engines → Active game registry: registers active game (evidence: `games/coin_steal.py`)
- Mini-game engines → Game content loader: loads questions (evidence: `games/trivia.py`)
- Game content loader → PostgreSQL storage: loads database content
- Sponsor campaigns → PostgreSQL storage: reads campaign data (evidence: `promotions/service.py`)
- Referral rewards → Subscription entitlements: grants rewards (evidence: `referral.py`)
- Payment handlers → Subscription entitlements: applies purchases (evidence: `handlers/payments.py`)
- Subscription entitlements → Shared runtime state: checks cached entitlements (evidence: `subscription.py`)
- Reports and restrictions → PostgreSQL storage: persists restrictions (evidence: `moderation.py`)
- Shared runtime state → PostgreSQL storage: loads and flushes users (evidence: `init.py`)
- Schema and migration → PostgreSQL storage: defines schema (evidence: `saveNload.py`)
- Telegram users → Anonymous voice calls: starts voice call
- Anonymous voice calls → Telegram API: launches WebApp room
- Telegram users → Health endpoint: requests health status
- Health endpoint → Telegram API: uses bot metrics
