# coolgromov/avabox architecture

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

- Interactive diagram: https://gitdiagram.com/coolgromov/avabox
- Repository: https://github.com/coolgromov/avabox

## Overview

AvaBox is a set of custom modules for the AvaCity virtual-world game server, with a companion web service and VK bot. The main player-facing capabilities cover avatar and inventory changes, social relationships and clans, room activities, and trading; web flows provide account access and payment-related functionality. The tree shows these modules but not the game server’s dispatcher, so links from clients into individual game modules are omitted. Redis usage is visible in sampled modules; several other capabilities are documented in the README but their internal wiring was not sampled.

Main entry points: [`web.py`](https://github.com/coolgromov/avabox/blob/main/web.py) (Web Service), [`utils/bot_vk.py`](https://github.com/coolgromov/avabox/blob/main/utils/bot_vk.py) (VK Bot), [`modules/avatar.py`](https://github.com/coolgromov/avabox/blob/main/modules/avatar.py) (Avatar), [`modules/relations.py`](https://github.com/coolgromov/avabox/blob/main/modules/relations.py) (Relationships)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and Payments"]
  node_web_app["Web Service<br/>[web.py]"]
  node_unitpay["UnitPay"]
end

subgraph group_player["Player and Economy"]
  node_avatar["Avatar<br/>[avatar.py]"]
  node_inventory["Inventory<br/>[inventory.py]"]
  node_shop["Shop<br/>[shop.py]"]
  node_billing["Billing<br/>[billing.py]"]
  node_craft["Crafting<br/>[craft.py]"]
end

subgraph group_social["Social World"]
  node_relations["Relationships<br/>[relations.py]"]
  node_clan["Clans<br/>[clan.py]"]
  node_trade["Trading<br/>[trade.py]"]
  node_mail["Mail<br/>[mail.py]"]
end

subgraph group_activities["Activities"]
  node_location["Rooms and Actions<br/>[location.py]"]
  node_house["Housing<br/>[house.py]"]
  node_location_game["Location Games<br/>[location_game.py]"]
end

subgraph group_operations["Community Operations"]
  node_campaign["Campaigns<br/>[campaign.py]"]
  node_news["News<br/>[news.py]"]
  node_component["Chat and Moderation<br/>[component.py]"]
  node_vk_bot["VK Bot<br/>[bot_vk.py]"]
end

node_players(("Players"))
node_game_client(("Game Client"))
node_vk_users(("VK Users"))
node_redis[("Redis")]

node_players -->|"use web routes"| node_web_app
node_web_app -->|"read/write"| node_redis
node_web_app -.->|"payment integration"| node_unitpay
node_vk_users -->|"send commands"| node_vk_bot
node_vk_bot -->|"read/write"| node_redis
node_avatar -->|"read/write"| node_redis
node_location -->|"read/write"| node_redis
node_clan -->|"read/write"| node_redis
node_relations -->|"read/write"| node_redis
node_game_client -->|"send game commands"| node_location_game

click node_web_app "https://github.com/coolgromov/avabox/blob/main/web.py"
click node_avatar "https://github.com/coolgromov/avabox/blob/main/modules/avatar.py"
click node_inventory "https://github.com/coolgromov/avabox/blob/main/modules/inventory.py"
click node_shop "https://github.com/coolgromov/avabox/blob/main/modules/shop.py"
click node_billing "https://github.com/coolgromov/avabox/blob/main/modules/billing.py"
click node_craft "https://github.com/coolgromov/avabox/blob/main/modules/craft.py"
click node_location "https://github.com/coolgromov/avabox/blob/main/modules/location.py"
click node_house "https://github.com/coolgromov/avabox/blob/main/modules/house.py"
click node_location_game "https://github.com/coolgromov/avabox/blob/main/modules/location_game.py"
click node_relations "https://github.com/coolgromov/avabox/blob/main/modules/relations.py"
click node_clan "https://github.com/coolgromov/avabox/blob/main/modules/clan.py"
click node_trade "https://github.com/coolgromov/avabox/blob/main/modules/trade.py"
click node_mail "https://github.com/coolgromov/avabox/blob/main/modules/mail.py"
click node_campaign "https://github.com/coolgromov/avabox/blob/main/modules/campaign.py"
click node_news "https://github.com/coolgromov/avabox/blob/main/modules/news.py"
click node_component "https://github.com/coolgromov/avabox/blob/main/modules/component.py"
click node_vk_bot "https://github.com/coolgromov/avabox/blob/main/utils/bot_vk.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_web_app,node_unitpay,node_game_client,node_vk_users toneBlue
class node_avatar,node_inventory,node_shop,node_billing,node_craft,node_redis toneAmber
class node_relations,node_clan,node_trade,node_mail toneMint
class node_location,node_house,node_location_game toneRose
class node_campaign,node_news,node_component,node_vk_bot,node_players toneIndigo
```

## Components

### Web and Payments

- [Web Service](https://github.com/coolgromov/avabox/blob/main/web.py): `web.py`
- **UnitPay**

### Player and Economy

- [Avatar](https://github.com/coolgromov/avabox/blob/main/modules/avatar.py): `modules/avatar.py`
- [Inventory](https://github.com/coolgromov/avabox/blob/main/modules/inventory.py): `modules/inventory.py`
- [Shop](https://github.com/coolgromov/avabox/blob/main/modules/shop.py): `modules/shop.py`
- [Billing](https://github.com/coolgromov/avabox/blob/main/modules/billing.py): `modules/billing.py`
- [Crafting](https://github.com/coolgromov/avabox/blob/main/modules/craft.py): `modules/craft.py`

### Social World

- [Relationships](https://github.com/coolgromov/avabox/blob/main/modules/relations.py): `modules/relations.py`
- [Clans](https://github.com/coolgromov/avabox/blob/main/modules/clan.py): `modules/clan.py`
- [Trading](https://github.com/coolgromov/avabox/blob/main/modules/trade.py): `modules/trade.py`
- [Mail](https://github.com/coolgromov/avabox/blob/main/modules/mail.py): `modules/mail.py`

### Activities

- [Rooms and Actions](https://github.com/coolgromov/avabox/blob/main/modules/location.py): `modules/location.py`
- [Housing](https://github.com/coolgromov/avabox/blob/main/modules/house.py): `modules/house.py`
- [Location Games](https://github.com/coolgromov/avabox/blob/main/modules/location_game.py): `modules/location_game.py`

### Community Operations

- [Campaigns](https://github.com/coolgromov/avabox/blob/main/modules/campaign.py): `modules/campaign.py`
- [News](https://github.com/coolgromov/avabox/blob/main/modules/news.py): `modules/news.py`
- [Chat and Moderation](https://github.com/coolgromov/avabox/blob/main/modules/component.py): `modules/component.py`
- [VK Bot](https://github.com/coolgromov/avabox/blob/main/utils/bot_vk.py): `utils/bot_vk.py`

### Other components

- **Players**
- **Game Client**
- **VK Users**
- **Redis**

## Connections

- Players → Web Service: use web routes
- Web Service → Redis: read/write
- Web Service → UnitPay: payment integration
- VK Users → VK Bot: send commands
- VK Bot → Redis: read/write
- Avatar → Redis: read/write
- Rooms and Actions → Redis: read/write
- Clans → Redis: read/write
- Relationships → Redis: read/write
- Game Client → Location Games: send game commands