# prashanthpathi/dota-2-ai-assistant architecture

> Architecture diagram of the GitHub repository prashanthpathi/dota-2-ai-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prashanthpathi/dota-2-ai-assistant
- Repository: https://github.com/prashanthpathi/dota-2-ai-assistant

## Overview

RealmMaster is an ADK-based tabletop RPG companion. A player or GM sends chat through the web proxy to the agent, which can answer with game tools and render rich A2UI responses. The repository also exposes A2A and reasoning-engine serving surfaces and shares session, artifact, and memory services across runtime paths. The README documents the game-tool integrations; sampled excerpts show server wiring and selected tool implementations, so undocumented internal tool-call details are not inferred.

Main entry points: [`app/agent.py`](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.py) (ADK Agent), [`app/fast_api_app.py`](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/fast_api_app.py) (FastAPI Server), [`frontend/static/index.html`](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/frontend/static/index.html) (Chat UI), [`app/app_utils/services.py`](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/app_utils/services.py) (Shared Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Chat Interface"]
  node_webproxy["Chat Proxy<br/>[main.py]"]
  node_webui["Chat UI<br/>[index.html]"]
end

subgraph group_runtime["Agent Runtime"]
  node_api["FastAPI Server<br/>[fast_api_app.py]"]
  node_a2a["A2A Routes<br/>[a2a.py]"]
  node_reasoning["Reasoning Adapter"]
  node_agent["ADK Agent<br/>[agent.py]"]
  node_services["Shared Services<br/>[services.py]"]
  node_a2ui["A2UI Formatter<br/>[a2ui_utils.py]"]
end

subgraph group_gameplay["Game Tools"]
  node_dice["Dice Roller<br/>[agent.py]"]
  node_catalog["Item Catalog<br/>[agent.py]"]
  node_inventory["Inventory Manager<br/>[agent.py]"]
  node_bestiary["Bestiary Lookup<br/>[agent.py]"]
  node_locations["Venue Finder<br/>[agent.py]"]
  node_artwork["Item Artwork<br/>[agent.py]"]
  node_sandbox["Code Sandbox<br/>[agent.py]"]
end

subgraph group_integrations["Cloud and External Services"]
  node_firestore[("Firestore")]
  node_memory[("Memory Bank")]
  node_artifactstore[("Artifact Storage")]
  node_vertex["Vertex AI"]
  node_maps["Google Maps APIs"]
  node_srd["5e SRD API"]
end

node_player(("Player or GM"))
node_browser(("Web Browser"))

node_player -->|"sends chat"| node_webui
node_webui -->|"posts chat"| node_webproxy
node_webproxy -->|"forwards A2A"| node_a2a
node_a2a -->|"dispatches requests"| node_agent
node_api -->|"registers routes"| node_a2a
node_api -->|"registers routes"| node_reasoning
node_reasoning -->|"dispatches methods"| node_agent
node_api -->|"builds runner"| node_agent
node_api -->|"gets shared services"| node_services
node_reasoning -->|"gets services"| node_services
node_agent -->|"provides tool"| node_dice
node_agent -->|"provides tools"| node_catalog
node_agent -->|"provides tool"| node_inventory
node_agent -->|"provides tool"| node_bestiary
node_agent -->|"provides tools"| node_locations
node_agent -->|"provides tool"| node_artwork
node_agent -->|"uses executor"| node_sandbox
node_catalog -->|"reads and writes"| node_firestore
node_inventory -->|"updates inventory"| node_firestore
node_bestiary -->|"fetches stats"| node_srd
node_locations -->|"queries places"| node_maps
node_artwork -->|"generates image"| node_vertex
node_artwork -->|"saves artifact"| node_artifactstore
node_sandbox -->|"executes sandbox"| node_vertex
node_agent -->|"preloads memories"| node_memory
node_services -->|"provides memory service"| node_memory
node_services -->|"provides artifact service"| node_artifactstore
node_agent -->|"formats responses"| node_a2ui
node_webproxy -->|"returns chat parts"| node_webui
node_webui -->|"renders cards"| node_browser

click node_webproxy "https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/frontend/main.py"
click node_webui "https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/frontend/static/index.html"
click node_api "https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/fast_api_app.py"
click node_a2a "https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/app_utils/a2a.py"
click node_reasoning "https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/app_utils/reasoning_engine_adapter.py"
click node_agent "https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.py"
click node_services "https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/app_utils/services.py"
click node_a2ui "https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/a2ui_utils.py"
click node_dice "https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.py"
click node_catalog "https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.py"
click node_inventory "https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.py"
click node_bestiary "https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.py"
click node_locations "https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.py"
click node_artwork "https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.py"
click node_sandbox "https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.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_webproxy,node_webui,node_browser toneBlue
class node_api,node_a2a,node_reasoning,node_agent,node_services,node_a2ui toneAmber
class node_dice,node_catalog,node_inventory,node_bestiary,node_locations,node_artwork,node_sandbox toneMint
class node_firestore,node_memory,node_artifactstore,node_vertex,node_maps,node_srd toneRose
class node_player toneIndigo
```

## Components

### Chat Interface

- [Chat Proxy](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/frontend/main.py): `frontend/main.py`
- [Chat UI](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/frontend/static/index.html): `frontend/static/index.html`

### Agent Runtime

- [FastAPI Server](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/fast_api_app.py): `app/fast_api_app.py`
- [A2A Routes](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/app_utils/a2a.py): `app/app_utils/a2a.py`
- [Reasoning Adapter](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/app_utils/reasoning_engine_adapter.py): `app/app_utils/reasoning_engine_adapter.py`
- [ADK Agent](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.py): `app/agent.py`
- [Shared Services](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/app_utils/services.py): `app/app_utils/services.py`
- [A2UI Formatter](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/a2ui_utils.py): `app/a2ui_utils.py`

### Game Tools

- [Dice Roller](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.py): `app/agent.py`
- [Item Catalog](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.py): `app/agent.py`
- [Inventory Manager](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.py): `app/agent.py`
- [Bestiary Lookup](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.py): `app/agent.py`
- [Venue Finder](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.py): `app/agent.py`
- [Item Artwork](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.py): `app/agent.py`
- [Code Sandbox](https://github.com/prashanthpathi/dota-2-ai-assistant/blob/main/app/agent.py): `app/agent.py`

### Cloud and External Services

- **Firestore**
- **Memory Bank**
- **Artifact Storage**
- **Vertex AI**
- **Google Maps APIs**
- **5e SRD API**

### Other components

- **Player or GM**
- **Web Browser**

## Connections

- Player or GM → Chat UI: sends chat (evidence: `README.md`)
- Chat UI → Chat Proxy: posts chat (evidence: `README.md`)
- Chat Proxy → A2A Routes: forwards A2A (evidence: `frontend/main.py`)
- A2A Routes → ADK Agent: dispatches requests (evidence: `app/fast_api_app.py`)
- FastAPI Server → A2A Routes: registers routes (evidence: `app/fast_api_app.py`)
- FastAPI Server → Reasoning Adapter: registers routes (evidence: `app/fast_api_app.py`)
- Reasoning Adapter → ADK Agent: dispatches methods (evidence: `app/app_utils/reasoning_engine_adapter.py`)
- FastAPI Server → ADK Agent: builds runner (evidence: `app/fast_api_app.py`)
- FastAPI Server → Shared Services: gets shared services (evidence: `app/fast_api_app.py`)
- Reasoning Adapter → Shared Services: gets services (evidence: `app/app_utils/reasoning_engine_adapter.py`)
- ADK Agent → Dice Roller: provides tool (evidence: `README.md`)
- ADK Agent → Item Catalog: provides tools (evidence: `README.md`)
- ADK Agent → Inventory Manager: provides tool (evidence: `README.md`)
- ADK Agent → Bestiary Lookup: provides tool (evidence: `README.md`)
- ADK Agent → Venue Finder: provides tools (evidence: `README.md`)
- ADK Agent → Item Artwork: provides tool (evidence: `README.md`)
- ADK Agent → Code Sandbox: uses executor (evidence: `README.md`)
- Item Catalog → Firestore: reads and writes (evidence: `README.md`)
- Inventory Manager → Firestore: updates inventory (evidence: `README.md`)
- Bestiary Lookup → 5e SRD API: fetches stats (evidence: `README.md`)
- Venue Finder → Google Maps APIs: queries places (evidence: `README.md`)
- Item Artwork → Vertex AI: generates image (evidence: `README.md`)
- Item Artwork → Artifact Storage: saves artifact (evidence: `README.md`)
- Code Sandbox → Vertex AI: executes sandbox (evidence: `README.md`)
- ADK Agent → Memory Bank: preloads memories (evidence: `README.md`)
- Shared Services → Memory Bank: provides memory service (evidence: `app/app_utils/services.py`)
- Shared Services → Artifact Storage: provides artifact service (evidence: `app/app_utils/services.py`)
- ADK Agent → A2UI Formatter: formats responses (evidence: `README.md`)
- Chat Proxy → Chat UI: returns chat parts (evidence: `frontend/main.py`)
- Chat UI → Web Browser: renders cards (evidence: `README.md`)
