# rimuwu/dinogochi architecture

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

- Interactive diagram: https://gitdiagram.com/rimuwu/dinogochi
- Repository: https://github.com/rimuwu/dinogochi

## Overview

#### Purpose and Entry Points
DinoGochi is a Python Telegram RPG/tamagotchi bot: users own dinosaurs, manage needs and activities, travel, craft, trade, fight, and participate in social/game systems. Process startup is `main.py`, with bot construction/runtime wiring in `bot/bot_instance.py` and executable/bootstrap logic in `bot/exec.py`. Configuration is generated/read through `bot/config.py`.

#### Telegram Request Pipeline
Telegram updates are routed into the extensive handler layer, organized by product domain: live activities, menus, combat, market, quests, crafting, arena, and inline interactions. Authorization, chat/type/state gating occur before handlers via filters; middleware provides cross-cutting antiflood, callback antiflood, logging, and worker-pass behavior.
- `bot/handlers/actions_live/`
- `bot/handlers/main_menu/`
- `bot/filters/`
- `bot/middlewares/`

#### Persistent Game State
MongoDB is the primary required datastore, accessed through dedicated database management code. Domain models represent persisted users, dinosaurs, groups, activities, items, market listings, arena, tavern, and tracking data. Redis is also materially present through a separate manager and Redis-backed user/tavern facilities, likely supporting cache or ephemeral coordination boundaries.
- `bot/dbmanager.py`
- `bot/redismanager.py`
- `bot/models/user.py`
- `bot/models/dinosaur.py`
- `bot/models/activity/`

#### Game Domain and Content Definition
The game’s durable rules/data boundary combines Python item/activity dataclasses and static JSON catalogs. Item classes encode behavior/categories; models represent active timed work such as collecting, crafting, journey, sleep, games, and training. JSON supplies dinosaurs, eggs, mobs, quests, shops, journey configuration, recipes, and item definitions, enabling content changes independently of much handler code.
- `bot/dataclasess/items/`
- `bot/models/activity/`
- `bot/json/items/`
- `bot/json/dinosaurs.json`

#### Domain Services and Gameplay Modules
Handlers delegate core operations to reusable modules for dinosaur state, inventory/items/crafting, combat strategy, market flows, quests, groups, dialogs, notifications, localization, and user features. This layer is the key boundary between Telegram-facing interaction code and database/content-backed game mutations.
- `bot/modules/dinosaur/`
- `bot/modules/items/`
- `bot/modules/combat/`
- `bot/modules/market/`
- `bot/modules/quests.py`

#### Timed Processing and Background Control Flow
A task subsystem advances time-dependent simulation independently of user messages: dinosaur states, incubation, journeys, sleep, collecting, crafting, games, market expiration, arena, events, notifications, subscriptions, backups, and reporting. Task orchestration/queue abstractions sit alongside these scheduled job implementations.
- `bot/taskmanager.py`
- `bot/modules/task_queue.py`
- `bot/tasks/`
- `bot/tasks/dino_states.py`

#### Integrations, Delivery, and Assets
The bot integrates Telegram as its primary external platform, MongoDB and Redis for state, plus payment/advertising-related modules (CryptoBot, Telegram Stars/invoices, donations, ads). Docker Compose packages the runtime; Nginx configuration and a webhook server module indicate deployment may support reverse-proxied webhook delivery rather than only polling. Localized UI strings and image/font assets support multilingual, media-rich responses.
- `docker-compose.yml`
- `nginx/nginx.conf.template`
- `bot/modules/webhook_server.py`
- `bot/modules/cryptobot.py`
- `bot/localization/`

Main entry points: [`bot/exec.py`](https://github.com/rimuwu/dinogochi/blob/main/bot/exec.py) (Bot bootstrap), [`bot/models/user.py`](https://github.com/rimuwu/dinogochi/blob/main/bot/models/user.py) (Game models), [`bot/bot_instance.py`](https://github.com/rimuwu/dinogochi/blob/main/bot/bot_instance.py) (Bot instance), [`bot/dbmanager.py`](https://github.com/rimuwu/dinogochi/blob/main/bot/dbmanager.py) (Mongo manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_entry["Process entry<br/>Python entrypoint<br/>[main.py]"]
  node_bootstrap["Bot bootstrap<br/>runtime wiring<br/>[exec.py]"]
  node_bot_instance["Bot instance<br/>Telegram runtime<br/>[bot_instance.py]"]
  node_config["Configuration<br/>config management<br/>[config.py]"]
end

subgraph group_telegram["Telegram Interface"]
  node_handlers["Domain handlers<br/>Telegram handlers"]
  node_filters["Filters<br/>authorization and gating"]
  node_middlewares["Middleware<br/>cross-cutting pipeline"]
end

subgraph group_gameplay["Game Domain"]
  node_game_modules["Gameplay modules<br/>domain services"]
  node_item_rules["Item rules<br/>item dataclasses"]
end

subgraph group_state["State &amp; Content"]
  node_models["Game models<br/>persistent domain models<br/>[user.py]"]
  node_activity_models["Activity models<br/>timed work models"]
  node_content["Content catalogs<br/>static JSON data"]
  node_mongo_manager["Mongo manager<br/>database access<br/>[dbmanager.py]"]
  node_redis_manager["Redis manager<br/>cache coordination<br/>[redismanager.py]"]
end

subgraph group_background["Background Processing"]
  node_task_manager["Task manager<br/>scheduler orchestration<br/>[taskmanager.py]"]
  node_task_queue["Task queue<br/>queue abstraction<br/>[task_queue.py]"]
  node_scheduled_tasks["Scheduled game tasks<br/>simulation jobs"]
end

subgraph group_external["External Services"]
  node_telegram{{"Telegram<br/>messaging platform"}}
  node_mongodb[("MongoDB<br/>primary datastore")]
  node_redis[("Redis<br/>ephemeral datastore")]
  node_webhook["Webhook delivery<br/>webhook server<br/>[webhook_server.py]"]
  node_payments{{"Payments and ads<br/>external monetization<br/>[cryptobot.py]"}}
end

node_entry -->|"starts"| node_bootstrap
node_bootstrap -->|"constructs"| node_bot_instance
node_bootstrap -->|"loads"| node_config
node_bot_instance -->|"processes through"| node_middlewares
node_middlewares -->|"applies"| node_filters
node_filters -->|"permits updates to"| node_handlers
node_telegram -->|"delivers updates"| node_bot_instance
node_webhook -->|"forwards webhook updates"| node_bot_instance
node_handlers -->|"delegates gameplay to"| node_game_modules
node_handlers -->|"initiates purchases and ads"| node_payments
node_game_modules -->|"uses"| node_item_rules
node_game_modules -->|"reads rules and catalogs"| node_content
node_game_modules -->|"reads and mutates"| node_models
node_models -->|"includes active work"| node_activity_models
node_models -->|"persists through"| node_mongo_manager
node_mongo_manager -->|"accesses"| node_mongodb
node_game_modules -.->|"uses ephemeral facilities"| node_redis_manager
node_redis_manager -->|"accesses"| node_redis
node_bootstrap -->|"starts"| node_task_manager
node_task_manager -->|"orchestrates"| node_task_queue
node_task_queue -->|"dispatches"| node_scheduled_tasks
node_scheduled_tasks -->|"advances game state via"| node_game_modules
node_scheduled_tasks -->|"updates"| node_models
node_scheduled_tasks -->|"persists state"| node_mongo_manager

click node_entry "https://github.com/rimuwu/dinogochi/blob/main/main.py"
click node_bootstrap "https://github.com/rimuwu/dinogochi/blob/main/bot/exec.py"
click node_bot_instance "https://github.com/rimuwu/dinogochi/blob/main/bot/bot_instance.py"
click node_config "https://github.com/rimuwu/dinogochi/blob/main/bot/config.py"
click node_models "https://github.com/rimuwu/dinogochi/blob/main/bot/models/user.py"
click node_mongo_manager "https://github.com/rimuwu/dinogochi/blob/main/bot/dbmanager.py"
click node_redis_manager "https://github.com/rimuwu/dinogochi/blob/main/bot/redismanager.py"
click node_task_manager "https://github.com/rimuwu/dinogochi/blob/main/bot/taskmanager.py"
click node_task_queue "https://github.com/rimuwu/dinogochi/blob/main/bot/modules/task_queue.py"
click node_webhook "https://github.com/rimuwu/dinogochi/blob/main/bot/modules/webhook_server.py"
click node_payments "https://github.com/rimuwu/dinogochi/blob/main/bot/modules/cryptobot.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_entry,node_bootstrap,node_bot_instance,node_config toneBlue
class node_handlers,node_filters,node_middlewares toneAmber
class node_game_modules,node_item_rules toneMint
class node_models,node_activity_models,node_content,node_mongo_manager,node_redis_manager toneRose
class node_task_manager,node_task_queue,node_scheduled_tasks toneIndigo
class node_telegram,node_mongodb,node_redis,node_webhook,node_payments toneTeal
```

## Components

### Runtime

- [Process entry](https://github.com/rimuwu/dinogochi/blob/main/main.py): Python entrypoint · `main.py`
- [Bot bootstrap](https://github.com/rimuwu/dinogochi/blob/main/bot/exec.py): runtime wiring · `bot/exec.py`
- [Bot instance](https://github.com/rimuwu/dinogochi/blob/main/bot/bot_instance.py): Telegram runtime · `bot/bot_instance.py`
- [Configuration](https://github.com/rimuwu/dinogochi/blob/main/bot/config.py): config management · `bot/config.py`

### Telegram Interface

- **Domain handlers**: Telegram handlers · Routes menus, activities, combat, market, quests, crafting, arena, and inline actions.
- **Filters**: authorization and gating
- **Middleware**: cross-cutting pipeline · Provides antiflood, callback protection, logging, and worker-pass behavior.

### Game Domain

- **Gameplay modules**: domain services · Mutate game state for dinosaurs, items, combat, market, quests, groups, and dialogs.
- **Item rules**: item dataclasses

### State & Content

- [Game models](https://github.com/rimuwu/dinogochi/blob/main/bot/models/user.py): persistent domain models · Includes users, dinosaurs, groups, listings, and active timed activities. · `bot/models/user.py`
- **Activity models**: timed work models · Represents collecting, crafting, journeys, sleep, games, and training.
- **Content catalogs**: static JSON data · Defines items, dinosaurs, eggs, mobs, quests, shops, journeys, and recipes.
- [Mongo manager](https://github.com/rimuwu/dinogochi/blob/main/bot/dbmanager.py): database access · `bot/dbmanager.py`
- [Redis manager](https://github.com/rimuwu/dinogochi/blob/main/bot/redismanager.py): cache coordination · `bot/redismanager.py`

### Background Processing

- [Task manager](https://github.com/rimuwu/dinogochi/blob/main/bot/taskmanager.py): scheduler orchestration · `bot/taskmanager.py`
- [Task queue](https://github.com/rimuwu/dinogochi/blob/main/bot/modules/task_queue.py): queue abstraction · `bot/modules/task_queue.py`
- **Scheduled game tasks**: simulation jobs · Advances states, incubation, journeys, activities, markets, arena, events, notifications, backups, and reporting.

### External Services

- **Telegram**: messaging platform
- **MongoDB**: primary datastore
- **Redis**: ephemeral datastore
- [Webhook delivery](https://github.com/rimuwu/dinogochi/blob/main/bot/modules/webhook_server.py): webhook server · `bot/modules/webhook_server.py`
- [Payments and ads](https://github.com/rimuwu/dinogochi/blob/main/bot/modules/cryptobot.py): external monetization · Supports CryptoBot, Telegram Stars/invoices, donations, and advertising. · `bot/modules/cryptobot.py`

## Connections

- Process entry → Bot bootstrap: starts
- Bot bootstrap → Bot instance: constructs
- Bot bootstrap → Configuration: loads
- Bot instance → Middleware: processes through
- Middleware → Filters: applies
- Filters → Domain handlers: permits updates to
- Telegram → Bot instance: delivers updates
- Webhook delivery → Bot instance: forwards webhook updates
- Domain handlers → Gameplay modules: delegates gameplay to
- Domain handlers → Payments and ads: initiates purchases and ads
- Gameplay modules → Item rules: uses
- Gameplay modules → Content catalogs: reads rules and catalogs
- Gameplay modules → Game models: reads and mutates
- Game models → Activity models: includes active work
- Game models → Mongo manager: persists through
- Mongo manager → MongoDB: accesses
- Gameplay modules → Redis manager: uses ephemeral facilities
- Redis manager → Redis: accesses
- Bot bootstrap → Task manager: starts
- Task manager → Task queue: orchestrates
- Task queue → Scheduled game tasks: dispatches
- Scheduled game tasks → Gameplay modules: advances game state via
- Scheduled game tasks → Game models: updates
- Scheduled game tasks → Mongo manager: persists state