# yzy-ydm/aurora-roguelike-ai architecture

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

- Interactive diagram: https://gitdiagram.com/yzy-ydm/aurora-roguelike-ai
- Repository: https://github.com/yzy-ydm/aurora-roguelike-ai

## Overview

Aurora is a Godot client/server Roguelike backend: the game API handles accounts, player state, gameplay data, and saves, while a separate AI API generates dynamic content. The documented player flow is client → REST API → domain service → MySQL-backed game data; AI generation is a separate request path with provider integration and generation history. The tree and excerpts establish the main entry points and several route/service calls, but most gameplay and AI internals were not sampled, so their detailed wiring is intentionally summarized.

Main entry points: [`server/main.py`](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/main.py) (FastAPI Entry), [`server/ai/api/ai_routes.py`](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/api/ai_routes.py) (Generation Routes), [`server/app/database/connection.py`](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/database/connection.py) (MySQL Store), [`server/ai/main.py`](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/main.py) (AI API Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_game_api["Game API"]
  node_game_entry["FastAPI Entry<br/>[main.py]"]
  node_auth_routes["Auth Routes<br/>[router.py]"]
  node_player_routes["Player Routes<br/>[router.py]"]
  node_weapon_routes["Weapon Routes<br/>[router.py]"]
  node_save_routes["Save Routes<br/>[router.py]"]
  node_gameplay_routes["Gameplay Routes"]
end

subgraph group_game_domain["Game Domain"]
  node_auth_service["Auth Service<br/>[auth_service.py]"]
  node_player_service["Player Service<br/>[player_service.py]"]
  node_weapon_service["Weapon Service<br/>[weapon_service.py]"]
  node_save_service["Save Service<br/>[save_service.py]"]
  node_game_services["Gameplay Services"]
  node_game_db[("MySQL Store<br/>[connection.py]")]
end

subgraph group_ai_service["AI Generation"]
  node_ai_entry["AI API Entry<br/>[main.py]"]
  node_ai_routes["Generation Routes<br/>[ai_routes.py]"]
  node_ai_core["AI Service<br/>[ai_service.py]"]
  node_provider_factory["Provider Factory"]
  node_mock_provider["Mock Provider<br/>[llm_provider.py]"]
end

subgraph group_ai_support["AI Operations"]
  node_ai_cache[("Generation Cache<br/>[cache_manager.py]")]
  node_ai_history[("AI History Store<br/>[db_manager.py]")]
  node_ai_extended_db[("AI Profile Store")]
end

node_godot(("Godot Client"))
node_mimo{{"MiMo AI"}}
node_game_user(("Player"))

node_godot -->|"REST requests"| node_game_entry
node_game_entry -->|"registers"| node_auth_routes
node_game_entry -->|"registers"| node_player_routes
node_game_entry -->|"registers"| node_weapon_routes
node_game_entry -->|"registers"| node_save_routes
node_game_entry -->|"registers"| node_gameplay_routes
node_auth_routes -->|"calls"| node_auth_service
node_player_routes -->|"calls"| node_player_service
node_weapon_routes -->|"calls"| node_weapon_service
node_save_routes -->|"calls"| node_save_service
node_gameplay_routes -->|"delegates"| node_game_services
node_auth_service -->|"queries and writes"| node_game_db
node_player_service -->|"persists player"| node_game_db
node_weapon_service -->|"reads and writes"| node_game_db
node_save_service -->|"persists saves"| node_game_db
node_godot -->|"AI requests"| node_ai_entry
node_ai_entry -->|"dispatches"| node_ai_routes
node_ai_routes -->|"requests generation"| node_ai_core
node_ai_core -->|"selects provider"| node_provider_factory
node_provider_factory -.->|"calls model"| node_mimo
node_provider_factory -.->|"uses mock"| node_mock_provider
node_ai_routes -->|"uses cache"| node_ai_cache
node_ai_routes -->|"records history"| node_ai_history
node_ai_entry -->|"reads statistics"| node_ai_extended_db

click node_game_entry "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/main.py"
click node_auth_routes "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/api/auth/router.py"
click node_player_routes "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/api/player/router.py"
click node_weapon_routes "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/api/weapon/router.py"
click node_save_routes "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/api/save/router.py"
click node_gameplay_routes "https://github.com/yzy-ydm/aurora-roguelike-ai/tree/main/server/app/api"
click node_auth_service "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/services/auth_service.py"
click node_player_service "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/services/player_service.py"
click node_weapon_service "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/services/weapon_service.py"
click node_save_service "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/services/save_service.py"
click node_game_services "https://github.com/yzy-ydm/aurora-roguelike-ai/tree/main/server/app/services"
click node_game_db "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/database/connection.py"
click node_ai_entry "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/main.py"
click node_ai_routes "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/api/ai_routes.py"
click node_ai_core "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/services/ai_service.py"
click node_provider_factory "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/services/provider_factory.py"
click node_mock_provider "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/services/llm_provider.py"
click node_ai_cache "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/cache/cache_manager.py"
click node_ai_history "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/database/db_manager.py"
click node_ai_extended_db "https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/database/enhanced_db_manager.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_game_entry,node_auth_routes,node_player_routes,node_weapon_routes,node_save_routes,node_gameplay_routes,node_godot toneBlue
class node_auth_service,node_player_service,node_weapon_service,node_save_service,node_game_services,node_game_db toneAmber
class node_ai_entry,node_ai_routes,node_ai_core,node_provider_factory,node_mock_provider toneMint
class node_ai_cache,node_ai_history,node_ai_extended_db toneRose
class node_mimo,node_game_user toneIndigo
```

## Components

### Game API

- [FastAPI Entry](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/main.py): `server/main.py`
- [Auth Routes](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/api/auth/router.py): `server/app/api/auth/router.py`
- [Player Routes](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/api/player/router.py): `server/app/api/player/router.py`
- [Weapon Routes](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/api/weapon/router.py): `server/app/api/weapon/router.py`
- [Save Routes](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/api/save/router.py): `server/app/api/save/router.py`
- [Gameplay Routes](https://github.com/yzy-ydm/aurora-roguelike-ai/tree/main/server/app/api): `server/app/api`

### Game Domain

- [Auth Service](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/services/auth_service.py): `server/app/services/auth_service.py`
- [Player Service](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/services/player_service.py): `server/app/services/player_service.py`
- [Weapon Service](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/services/weapon_service.py): `server/app/services/weapon_service.py`
- [Save Service](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/services/save_service.py): `server/app/services/save_service.py`
- [Gameplay Services](https://github.com/yzy-ydm/aurora-roguelike-ai/tree/main/server/app/services): `server/app/services`
- [MySQL Store](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/app/database/connection.py): `server/app/database/connection.py`

### AI Generation

- [AI API Entry](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/main.py): `server/ai/main.py`
- [Generation Routes](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/api/ai_routes.py): `server/ai/api/ai_routes.py`
- [AI Service](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/services/ai_service.py): `server/ai/services/ai_service.py`
- [Provider Factory](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/services/provider_factory.py): `server/ai/services/provider_factory.py`
- [Mock Provider](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/services/llm_provider.py): `server/ai/services/llm_provider.py`

### AI Operations

- [Generation Cache](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/cache/cache_manager.py): `server/ai/cache/cache_manager.py`
- [AI History Store](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/database/db_manager.py): `server/ai/database/db_manager.py`
- [AI Profile Store](https://github.com/yzy-ydm/aurora-roguelike-ai/blob/main/server/ai/database/enhanced_db_manager.py): `server/ai/database/enhanced_db_manager.py`

### Other components

- **Godot Client**
- **MiMo AI**
- **Player**

## Connections

- Godot Client → FastAPI Entry: REST requests
- FastAPI Entry → Auth Routes: registers
- FastAPI Entry → Player Routes: registers
- FastAPI Entry → Weapon Routes: registers
- FastAPI Entry → Save Routes: registers
- FastAPI Entry → Gameplay Routes: registers
- Auth Routes → Auth Service: calls
- Player Routes → Player Service: calls
- Weapon Routes → Weapon Service: calls
- Save Routes → Save Service: calls
- Gameplay Routes → Gameplay Services: delegates
- Auth Service → MySQL Store: queries and writes
- Player Service → MySQL Store: persists player
- Weapon Service → MySQL Store: reads and writes
- Save Service → MySQL Store: persists saves
- Godot Client → AI API Entry: AI requests
- AI API Entry → Generation Routes: dispatches
- Generation Routes → AI Service: requests generation
- AI Service → Provider Factory: selects provider
- Provider Factory → MiMo AI: calls model
- Provider Factory → Mock Provider: uses mock
- Generation Routes → Generation Cache: uses cache
- Generation Routes → AI History Store: records history
- AI API Entry → AI Profile Store: reads statistics