# nacholedesma33/roleito-22w22 architecture

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

- Interactive diagram: https://gitdiagram.com/nacholedesma33/roleito-22w22
- Repository: https://github.com/nacholedesma33/roleito-22w22

## Overview

Roleito is a local-first AI-assisted tabletop RPG platform. The DM and players use the React app to manage campaigns and play in a virtual tabletop; backend APIs persist campaign state and expose domain features. For AI-assisted work, API handlers invoke agents that build canon-aware context and produce proposals, recaps, lore, or world-state views. The DM remains the authority over canon. The README documents the major product areas; several feature internals are represented by their exact enclosing directories because their implementation was not sampled.

Main entry points: [`core/agents`](https://github.com/nacholedesma33/roleito-22w22/tree/main/core/agents) (Specialist agents), [`core/agents/orchestrator.py`](https://github.com/nacholedesma33/roleito-22w22/blob/main/core/agents/orchestrator.py) (Agent coordinator), [`backend/models.py`](https://github.com/nacholedesma33/roleito-22w22/blob/main/backend/models.py) (Campaign records), [`backend/scene_routes.py`](https://github.com/nacholedesma33/roleito-22w22/blob/main/backend/scene_routes.py) (Scene APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React client"]
  node_app["Application shell<br/>[App.tsx]"]
  node_vtt["Virtual tabletop"]
  node_player_view["Player view<br/>[PlayerView.tsx]"]
  node_campaign_ui["Campaign tools"]
end

subgraph group_api["Backend API"]
  node_api_routes["Campaign APIs<br/>[routes.py]"]
  node_scene_api["Scene APIs<br/>[scene_routes.py]"]
  node_agent_api["Agent APIs<br/>[agent_routes.py]"]
  node_orchestrator_api["Orchestrator API"]
  node_database["SQLite access<br/>[database.py]"]
end

subgraph group_domain["Campaign domain"]
  node_campaign_data[("Campaign records<br/>[models.py]")]
  node_wall_detection["Map detection"]
  node_world_state["World state<br/>[engine.py]"]
  node_canon["Canon review<br/>[manager.py]"]
  node_memory["Persistent memory<br/>[builder.py]"]
  node_narrative["Narrative parsing"]
end

subgraph group_agents["AI assistance"]
  node_agent_orchestrator["Agent coordinator<br/>[orchestrator.py]"]
  node_agent_context["Safe context<br/>[context_manager.py]"]
  node_agent_skills["Specialist agents"]
end

subgraph group_integrations["AI providers"]
  node_provider["Provider selection<br/>[provider.py]"]
  node_ai_adapters["AI adapters"]
end

node_dm(("DM"))
node_players(("Players"))

node_dm -->|"uses"| node_app
node_players -->|"play through"| node_player_view
node_app -->|"renders"| node_campaign_ui
node_app -.->|"uses APIs"| node_api_routes
node_campaign_ui -.->|"manages campaigns"| node_api_routes
node_vtt -.->|"manages scenes"| node_scene_api
node_player_view -.->|"views scenes"| node_scene_api
node_scene_api -->|"invokes detection"| node_wall_detection
node_api_routes -->|"reads and writes"| node_campaign_data
node_scene_api -->|"reads and writes"| node_campaign_data
node_database -->|"maps models"| node_campaign_data
node_agent_api -->|"invokes agents"| node_agent_skills
node_orchestrator_api -->|"executes tasks"| node_agent_orchestrator
node_agent_orchestrator -->|"coordinates"| node_agent_skills
node_agent_orchestrator -->|"builds context"| node_agent_context
node_agent_orchestrator -->|"requests state"| node_world_state
node_agent_orchestrator -->|"loads campaign data"| node_campaign_data
node_world_state -->|"reads events"| node_campaign_data
node_agent_skills -.->|"proposes canon"| node_canon
node_agent_skills -.->|"uses persistent memory"| node_memory
node_agent_skills -.->|"uses narrative tools"| node_narrative
node_agent_skills -->|"gets provider"| node_provider
node_provider -->|"builds provider"| node_ai_adapters

click node_app "https://github.com/nacholedesma33/roleito-22w22/blob/main/apps/dm/src/App.tsx"
click node_vtt "https://github.com/nacholedesma33/roleito-22w22/tree/main/apps/dm/src/components"
click node_player_view "https://github.com/nacholedesma33/roleito-22w22/blob/main/apps/dm/src/pages/PlayerView.tsx"
click node_campaign_ui "https://github.com/nacholedesma33/roleito-22w22/tree/main/apps/dm/src/pages"
click node_api_routes "https://github.com/nacholedesma33/roleito-22w22/blob/main/backend/routes.py"
click node_scene_api "https://github.com/nacholedesma33/roleito-22w22/blob/main/backend/scene_routes.py"
click node_agent_api "https://github.com/nacholedesma33/roleito-22w22/blob/main/backend/agent_routes.py"
click node_orchestrator_api "https://github.com/nacholedesma33/roleito-22w22/blob/main/backend/orchestrator_routes.py"
click node_database "https://github.com/nacholedesma33/roleito-22w22/blob/main/backend/database.py"
click node_campaign_data "https://github.com/nacholedesma33/roleito-22w22/blob/main/backend/models.py"
click node_wall_detection "https://github.com/nacholedesma33/roleito-22w22/tree/main/backend/wall_detection"
click node_world_state "https://github.com/nacholedesma33/roleito-22w22/blob/main/core/world/engine.py"
click node_canon "https://github.com/nacholedesma33/roleito-22w22/blob/main/core/canon/manager.py"
click node_memory "https://github.com/nacholedesma33/roleito-22w22/blob/main/core/memory/builder.py"
click node_narrative "https://github.com/nacholedesma33/roleito-22w22/tree/main/core/narrative"
click node_agent_orchestrator "https://github.com/nacholedesma33/roleito-22w22/blob/main/core/agents/orchestrator.py"
click node_agent_context "https://github.com/nacholedesma33/roleito-22w22/blob/main/core/agents/context_manager.py"
click node_agent_skills "https://github.com/nacholedesma33/roleito-22w22/tree/main/core/agents"
click node_provider "https://github.com/nacholedesma33/roleito-22w22/blob/main/core/agents/provider.py"
click node_ai_adapters "https://github.com/nacholedesma33/roleito-22w22/tree/main/infrastructure/ai"

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_app,node_vtt,node_player_view,node_campaign_ui toneBlue
class node_api_routes,node_scene_api,node_agent_api,node_orchestrator_api,node_database toneAmber
class node_campaign_data,node_wall_detection,node_world_state,node_canon,node_memory,node_narrative toneMint
class node_agent_orchestrator,node_agent_context,node_agent_skills toneRose
class node_provider,node_ai_adapters,node_dm,node_players toneIndigo
```

## Components

### React client

- [Application shell](https://github.com/nacholedesma33/roleito-22w22/blob/main/apps/dm/src/App.tsx): `apps/dm/src/App.tsx`
- [Virtual tabletop](https://github.com/nacholedesma33/roleito-22w22/tree/main/apps/dm/src/components): `apps/dm/src/components`
- [Player view](https://github.com/nacholedesma33/roleito-22w22/blob/main/apps/dm/src/pages/PlayerView.tsx): `apps/dm/src/pages/PlayerView.tsx`
- [Campaign tools](https://github.com/nacholedesma33/roleito-22w22/tree/main/apps/dm/src/pages): `apps/dm/src/pages`

### Backend API

- [Campaign APIs](https://github.com/nacholedesma33/roleito-22w22/blob/main/backend/routes.py): `backend/routes.py`
- [Scene APIs](https://github.com/nacholedesma33/roleito-22w22/blob/main/backend/scene_routes.py): `backend/scene_routes.py`
- [Agent APIs](https://github.com/nacholedesma33/roleito-22w22/blob/main/backend/agent_routes.py): `backend/agent_routes.py`
- [Orchestrator API](https://github.com/nacholedesma33/roleito-22w22/blob/main/backend/orchestrator_routes.py): `backend/orchestrator_routes.py`
- [SQLite access](https://github.com/nacholedesma33/roleito-22w22/blob/main/backend/database.py): `backend/database.py`

### Campaign domain

- [Campaign records](https://github.com/nacholedesma33/roleito-22w22/blob/main/backend/models.py): `backend/models.py`
- [Map detection](https://github.com/nacholedesma33/roleito-22w22/tree/main/backend/wall_detection): `backend/wall_detection`
- [World state](https://github.com/nacholedesma33/roleito-22w22/blob/main/core/world/engine.py): `core/world/engine.py`
- [Canon review](https://github.com/nacholedesma33/roleito-22w22/blob/main/core/canon/manager.py): `core/canon/manager.py`
- [Persistent memory](https://github.com/nacholedesma33/roleito-22w22/blob/main/core/memory/builder.py): `core/memory/builder.py`
- [Narrative parsing](https://github.com/nacholedesma33/roleito-22w22/tree/main/core/narrative): `core/narrative`

### AI assistance

- [Agent coordinator](https://github.com/nacholedesma33/roleito-22w22/blob/main/core/agents/orchestrator.py): `core/agents/orchestrator.py`
- [Safe context](https://github.com/nacholedesma33/roleito-22w22/blob/main/core/agents/context_manager.py): `core/agents/context_manager.py`
- [Specialist agents](https://github.com/nacholedesma33/roleito-22w22/tree/main/core/agents): `core/agents`

### AI providers

- [Provider selection](https://github.com/nacholedesma33/roleito-22w22/blob/main/core/agents/provider.py): `core/agents/provider.py`
- [AI adapters](https://github.com/nacholedesma33/roleito-22w22/tree/main/infrastructure/ai): `infrastructure/ai`

### Other components

- **DM**
- **Players**

## Connections

- DM → Application shell: uses
- Players → Player view: play through
- Application shell → Campaign tools: renders (evidence: `apps/dm/src/App.tsx`)
- Application shell → Campaign APIs: uses APIs
- Campaign tools → Campaign APIs: manages campaigns
- Virtual tabletop → Scene APIs: manages scenes
- Player view → Scene APIs: views scenes
- Scene APIs → Map detection: invokes detection (evidence: `backend/scene_routes.py`)
- Campaign APIs → Campaign records: reads and writes (evidence: `backend/routes.py`)
- Scene APIs → Campaign records: reads and writes (evidence: `backend/scene_routes.py`)
- SQLite access → Campaign records: maps models (evidence: `backend/database.py`)
- Agent APIs → Specialist agents: invokes agents (evidence: `backend/agent_routes.py`)
- Orchestrator API → Agent coordinator: executes tasks (evidence: `backend/orchestrator_routes.py`)
- Agent coordinator → Specialist agents: coordinates (evidence: `core/agents/orchestrator.py`)
- Agent coordinator → Safe context: builds context (evidence: `core/agents/orchestrator.py`)
- Agent coordinator → World state: requests state (evidence: `core/agents/orchestrator.py`)
- Agent coordinator → Campaign records: loads campaign data (evidence: `core/agents/orchestrator.py`)
- World state → Campaign records: reads events (evidence: `core/world/engine.py`)
- Specialist agents → Canon review: proposes canon
- Specialist agents → Persistent memory: uses persistent memory
- Specialist agents → Narrative parsing: uses narrative tools (evidence: `core/agents/proposals.py`)
- Specialist agents → Provider selection: gets provider (evidence: `backend/agent_routes.py`)
- Provider selection → AI adapters: builds provider (evidence: `core/agents/provider.py`)
