# orurh/catforge_bot architecture

> Architecture diagram of the GitHub repository orurh/catforge_bot, 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/orurh/catforge_bot
- Repository: https://github.com/orurh/catforge_bot

## Overview

CatForge is a social Telegram cat game. Players create and manage a cat, train it, join Yard events, and toggle into arena fights; results update progression and can appear in chat. Weekly summaries and personality-driven speech extend that core loop, while Stars support is explicitly non-gameplay. The README says Expedition and Bestiary are currently disabled. The excerpts show app service construction and the remote engine boundary; several transport-to-service and persistence connections are documented only at product level or remain unverified, so those links are omitted or marked dashed.

Main entry points: [`internal/app/app.go`](https://github.com/orurh/catforge_bot/blob/main/internal/app/app.go) (Application wiring), [`internal/transport/telegram/router.go`](https://github.com/orurh/catforge_bot/blob/main/internal/transport/telegram/router.go) (Bot transport), [`internal/gameengine/grpc_engine.go`](https://github.com/orurh/catforge_bot/blob/main/internal/gameengine/grpc_engine.go) (Engine client), [`internal/app/cat_banter_service.go`](https://github.com/orurh/catforge_bot/blob/main/internal/app/cat_banter_service.go) (Cat speech)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Telegram experience"]
  node_transport["Bot transport<br/>[router.go]"]
end

subgraph group_application["Game application"]
  node_app["Application wiring<br/>[app.go]"]
  node_cat_setup["Cat setup and profile<br/>[starter_service.go]"]
  node_training["Training"]
  node_yard["Yard events"]
  node_arena["Arena fights<br/>[fight_service.go]"]
  node_weekly["Weekly summary"]
  node_speech_service["Cat speech"]
  node_payments["Stars support<br/>[payment_service.go]"]
end

subgraph group_state["Persistent state"]
  node_postgres[("Postgres repositories")]
end

subgraph group_engine["Deterministic engine"]
  node_game_engine_client["Engine client<br/>[grpc_engine.go]"]
  node_grpc_contract["Engine RPC contract<br/>[game_engine.proto]"]
  node_grpc_service["C++ RPC service<br/>[grpc_service.cpp]"]
  node_cpp_rules["Game rules<br/>[game_engine.cpp]"]
end

subgraph group_speech["AI and speech"]
  node_ai_gateway["AI providers<br/>[gateway.go]"]
  node_game_content["Procedural content<br/>[catalog.go]"]
end

node_player(("Player"))
node_telegram(("Telegram"))
node_telegram_api["Telegram API"]
node_ai_provider["AI provider"]

node_player -->|"sends commands"| node_telegram
node_telegram -.->|"delivers updates"| node_transport
node_transport -.->|"dispatches actions"| node_app
node_app -->|"constructs service"| node_cat_setup
node_app -->|"constructs service"| node_training
node_app -->|"constructs service"| node_yard
node_app -->|"constructs service"| node_arena
node_app -->|"constructs service"| node_weekly
node_app -->|"constructs service"| node_speech_service
node_app -->|"exposes service"| node_payments
node_training -.->|"resolves training"| node_game_engine_client
node_arena -.->|"resolves fight"| node_game_engine_client
node_yard -.->|"resolves event"| node_game_engine_client
node_game_engine_client -->|"uses RPC contract"| node_grpc_contract
node_grpc_service -.->|"runs rules"| node_cpp_rules
node_telegram -.->|"receives bot replies"| node_transport
node_transport -.->|"sends messages"| node_telegram_api
node_speech_service -.->|"generates speech"| node_ai_gateway
node_ai_gateway -.->|"requests generation"| node_ai_provider
node_speech_service -.->|"uses fallback text"| node_game_content
node_player -->|"requests support"| node_transport
node_player -->|"starts game actions"| node_transport

click node_transport "https://github.com/orurh/catforge_bot/blob/main/internal/transport/telegram/router.go"
click node_app "https://github.com/orurh/catforge_bot/blob/main/internal/app/app.go"
click node_cat_setup "https://github.com/orurh/catforge_bot/blob/main/internal/app/starter_service.go"
click node_training "https://github.com/orurh/catforge_bot/blob/main/internal/app/training_service.go"
click node_yard "https://github.com/orurh/catforge_bot/blob/main/internal/app/yard_event_service.go"
click node_arena "https://github.com/orurh/catforge_bot/blob/main/internal/app/fight_service.go"
click node_weekly "https://github.com/orurh/catforge_bot/blob/main/internal/app/weekly_summary_service.go"
click node_speech_service "https://github.com/orurh/catforge_bot/blob/main/internal/app/cat_banter_service.go"
click node_payments "https://github.com/orurh/catforge_bot/blob/main/internal/app/payment_service.go"
click node_postgres "https://github.com/orurh/catforge_bot/tree/main/internal/repo/postgres"
click node_game_engine_client "https://github.com/orurh/catforge_bot/blob/main/internal/gameengine/grpc_engine.go"
click node_grpc_contract "https://github.com/orurh/catforge_bot/blob/main/api/gameengine/v1/game_engine.proto"
click node_grpc_service "https://github.com/orurh/catforge_bot/blob/main/engine_cpp/src/grpc_service.cpp"
click node_cpp_rules "https://github.com/orurh/catforge_bot/blob/main/engine_cpp/src/game_engine.cpp"
click node_ai_gateway "https://github.com/orurh/catforge_bot/blob/main/internal/ai/gateway.go"
click node_game_content "https://github.com/orurh/catforge_bot/blob/main/internal/gamecontent/catalog.go"

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_transport toneBlue
class node_app,node_cat_setup,node_training,node_yard,node_arena,node_weekly,node_speech_service,node_payments toneAmber
class node_postgres,node_telegram_api toneMint
class node_game_engine_client,node_grpc_contract,node_grpc_service,node_cpp_rules toneRose
class node_ai_gateway,node_game_content,node_player,node_telegram,node_ai_provider toneIndigo
```

## Components

### Telegram experience

- [Bot transport](https://github.com/orurh/catforge_bot/blob/main/internal/transport/telegram/router.go): `internal/transport/telegram/router.go`

### Game application

- [Application wiring](https://github.com/orurh/catforge_bot/blob/main/internal/app/app.go): `internal/app/app.go`
- [Cat setup and profile](https://github.com/orurh/catforge_bot/blob/main/internal/app/starter_service.go): `internal/app/starter_service.go`
- [Training](https://github.com/orurh/catforge_bot/blob/main/internal/app/training_service.go): `internal/app/training_service.go`
- [Yard events](https://github.com/orurh/catforge_bot/blob/main/internal/app/yard_event_service.go): `internal/app/yard_event_service.go`
- [Arena fights](https://github.com/orurh/catforge_bot/blob/main/internal/app/fight_service.go): `internal/app/fight_service.go`
- [Weekly summary](https://github.com/orurh/catforge_bot/blob/main/internal/app/weekly_summary_service.go): `internal/app/weekly_summary_service.go`
- [Cat speech](https://github.com/orurh/catforge_bot/blob/main/internal/app/cat_banter_service.go): `internal/app/cat_banter_service.go`
- [Stars support](https://github.com/orurh/catforge_bot/blob/main/internal/app/payment_service.go): `internal/app/payment_service.go`

### Persistent state

- [Postgres repositories](https://github.com/orurh/catforge_bot/tree/main/internal/repo/postgres): `internal/repo/postgres`

### Deterministic engine

- [Engine client](https://github.com/orurh/catforge_bot/blob/main/internal/gameengine/grpc_engine.go): `internal/gameengine/grpc_engine.go`
- [Engine RPC contract](https://github.com/orurh/catforge_bot/blob/main/api/gameengine/v1/game_engine.proto): `api/gameengine/v1/game_engine.proto`
- [C++ RPC service](https://github.com/orurh/catforge_bot/blob/main/engine_cpp/src/grpc_service.cpp): `engine_cpp/src/grpc_service.cpp`
- [Game rules](https://github.com/orurh/catforge_bot/blob/main/engine_cpp/src/game_engine.cpp): `engine_cpp/src/game_engine.cpp`

### AI and speech

- [AI providers](https://github.com/orurh/catforge_bot/blob/main/internal/ai/gateway.go): `internal/ai/gateway.go`
- [Procedural content](https://github.com/orurh/catforge_bot/blob/main/internal/gamecontent/catalog.go): `internal/gamecontent/catalog.go`

### Other components

- **Player**
- **Telegram**
- **Telegram API**
- **AI provider**

## Connections

- Player → Telegram: sends commands
- Telegram → Bot transport: delivers updates
- Bot transport → Application wiring: dispatches actions
- Application wiring → Cat setup and profile: constructs service (evidence: `internal/app/app.go`)
- Application wiring → Training: constructs service (evidence: `internal/app/app.go`)
- Application wiring → Yard events: constructs service (evidence: `internal/app/app.go`)
- Application wiring → Arena fights: constructs service (evidence: `internal/app/app.go`)
- Application wiring → Weekly summary: constructs service (evidence: `internal/app/app.go`)
- Application wiring → Cat speech: constructs service (evidence: `internal/app/app.go`)
- Application wiring → Stars support: exposes service (evidence: `internal/app/app.go`)
- Training → Engine client: resolves training
- Arena fights → Engine client: resolves fight
- Yard events → Engine client: resolves event
- Engine client → Engine RPC contract: uses RPC contract (evidence: `internal/gameengine/grpc_engine.go`)
- C++ RPC service → Game rules: runs rules
- Telegram → Bot transport: receives bot replies
- Bot transport → Telegram API: sends messages
- Cat speech → AI providers: generates speech
- AI providers → AI provider: requests generation
- Cat speech → Procedural content: uses fallback text
- Player → Bot transport: requests support
- Player → Bot transport: starts game actions
