# villanuevayanmar/tagbound architecture

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

## Overview

TAGBOUND is a browser-playable rooftop chase game: the player selects a class, starts or resumes a saved run, traverses city beacon quests and boss encounters, and earns persistent progression. The C++ runtime owns simulation, combat, progression, and rendering; the browser layer supplies touch input, story/install UI, audio, and offline caching. Edges follow sampled callers or README statements; several product capabilities are documented but their detailed implementation was not sampled.

Main entry points: [`src/main.cpp`](https://github.com/villanuevayanmar/tagbound/blob/main/src/main.cpp) (Game Loop), [`web/pwa.js`](https://github.com/villanuevayanmar/tagbound/blob/main/web/pwa.js) (Touch and Story UI), [`src/game.hpp`](https://github.com/villanuevayanmar/tagbound/blob/main/src/game.hpp) (Game State), [`src/systems.cpp`](https://github.com/villanuevayanmar/tagbound/blob/main/src/systems.cpp) (Combat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser Experience"]
  node_pwa_ui["Touch and Story UI<br/>[pwa.js]"]
  node_audio["Synth Audio<br/>[pwa.js]"]
  node_offline["Offline PWA<br/>[sw.js]"]
  node_service[("Browser Cache<br/>[sw.js]")]
end

subgraph group_runtime["Game Runtime"]
  node_entry["Game Loop<br/>[main.cpp]"]
  node_controls["Input Mapping<br/>[main.cpp]"]
  node_movement["Traversal<br/>[systems.cpp]"]
  node_pursuit["Pursuer AI<br/>[systems.cpp]"]
  node_combat["Combat<br/>[systems.cpp]"]
  node_projectiles["Projectile Combat<br/>[systems.cpp]"]
end

subgraph group_world["World and Progress"]
  node_progression["XP and Skills<br/>[systems.cpp]"]
  node_cities["City Builder<br/>[game.cpp]"]
  node_quests["Beacon Quests<br/>[game.cpp]"]
  node_bosses["Boss Encounters<br/>[game.cpp]"]
end

subgraph group_support["Presentation and Persistence"]
  node_state["Game State<br/>[game.hpp]"]
  node_renderer["3D Renderer and HUD<br/>[render.cpp]"]
  node_save[("Local Progress Save<br/>[main.cpp]")]
end

node_player(("Player"))

node_player -->|"uses controls"| node_pwa_ui
node_pwa_ui -->|"calls exports"| node_entry
node_entry -->|"reads input"| node_controls
node_controls -->|"updates movement"| node_movement
node_entry -->|"updates pursuit"| node_pursuit
node_entry -->|"updates combat"| node_combat
node_combat -->|"advances shots"| node_projectiles
node_entry -->|"builds city"| node_cities
node_entry -->|"checks progress"| node_quests
node_quests -->|"unlocks boss"| node_bosses
node_entry -->|"awards XP"| node_progression
node_entry -->|"draws frame"| node_renderer
node_entry -->|"loads and saves"| node_save
node_entry -->|"plays effects"| node_audio
node_pwa_ui -->|"toggles sound"| node_audio
node_pwa_ui -->|"registers worker"| node_offline
node_offline -->|"caches assets"| node_service
node_movement -->|"updates state"| node_state
node_pursuit -->|"updates state"| node_state
node_combat -->|"updates state"| node_state
node_renderer -->|"renders state"| node_state

click node_pwa_ui "https://github.com/villanuevayanmar/tagbound/blob/main/web/pwa.js"
click node_audio "https://github.com/villanuevayanmar/tagbound/blob/main/web/pwa.js"
click node_offline "https://github.com/villanuevayanmar/tagbound/blob/main/web/sw.js"
click node_entry "https://github.com/villanuevayanmar/tagbound/blob/main/src/main.cpp"
click node_controls "https://github.com/villanuevayanmar/tagbound/blob/main/src/main.cpp"
click node_movement "https://github.com/villanuevayanmar/tagbound/blob/main/src/systems.cpp"
click node_pursuit "https://github.com/villanuevayanmar/tagbound/blob/main/src/systems.cpp"
click node_combat "https://github.com/villanuevayanmar/tagbound/blob/main/src/systems.cpp"
click node_projectiles "https://github.com/villanuevayanmar/tagbound/blob/main/src/systems.cpp"
click node_progression "https://github.com/villanuevayanmar/tagbound/blob/main/src/systems.cpp"
click node_cities "https://github.com/villanuevayanmar/tagbound/blob/main/src/game.cpp"
click node_quests "https://github.com/villanuevayanmar/tagbound/blob/main/src/game.cpp"
click node_bosses "https://github.com/villanuevayanmar/tagbound/blob/main/src/game.cpp"
click node_state "https://github.com/villanuevayanmar/tagbound/blob/main/src/game.hpp"
click node_renderer "https://github.com/villanuevayanmar/tagbound/blob/main/src/render.cpp"
click node_save "https://github.com/villanuevayanmar/tagbound/blob/main/src/main.cpp"
click node_service "https://github.com/villanuevayanmar/tagbound/blob/main/web/sw.js"

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_pwa_ui,node_audio,node_offline,node_service toneBlue
class node_entry,node_controls,node_movement,node_pursuit,node_combat,node_projectiles toneAmber
class node_progression,node_cities,node_quests,node_bosses toneMint
class node_state,node_renderer,node_save toneRose
class node_player toneIndigo
```

## Components

### Browser Experience

- [Touch and Story UI](https://github.com/villanuevayanmar/tagbound/blob/main/web/pwa.js): `web/pwa.js`
- [Synth Audio](https://github.com/villanuevayanmar/tagbound/blob/main/web/pwa.js): `web/pwa.js`
- [Offline PWA](https://github.com/villanuevayanmar/tagbound/blob/main/web/sw.js): `web/sw.js`
- [Browser Cache](https://github.com/villanuevayanmar/tagbound/blob/main/web/sw.js): `web/sw.js`

### Game Runtime

- [Game Loop](https://github.com/villanuevayanmar/tagbound/blob/main/src/main.cpp): `src/main.cpp`
- [Input Mapping](https://github.com/villanuevayanmar/tagbound/blob/main/src/main.cpp): `src/main.cpp`
- [Traversal](https://github.com/villanuevayanmar/tagbound/blob/main/src/systems.cpp): `src/systems.cpp`
- [Pursuer AI](https://github.com/villanuevayanmar/tagbound/blob/main/src/systems.cpp): `src/systems.cpp`
- [Combat](https://github.com/villanuevayanmar/tagbound/blob/main/src/systems.cpp): `src/systems.cpp`
- [Projectile Combat](https://github.com/villanuevayanmar/tagbound/blob/main/src/systems.cpp): `src/systems.cpp`

### World and Progress

- [XP and Skills](https://github.com/villanuevayanmar/tagbound/blob/main/src/systems.cpp): `src/systems.cpp`
- [City Builder](https://github.com/villanuevayanmar/tagbound/blob/main/src/game.cpp): `src/game.cpp`
- [Beacon Quests](https://github.com/villanuevayanmar/tagbound/blob/main/src/game.cpp): `src/game.cpp`
- [Boss Encounters](https://github.com/villanuevayanmar/tagbound/blob/main/src/game.cpp): `src/game.cpp`

### Presentation and Persistence

- [Game State](https://github.com/villanuevayanmar/tagbound/blob/main/src/game.hpp): `src/game.hpp`
- [3D Renderer and HUD](https://github.com/villanuevayanmar/tagbound/blob/main/src/render.cpp): `src/render.cpp`
- [Local Progress Save](https://github.com/villanuevayanmar/tagbound/blob/main/src/main.cpp): `src/main.cpp`

### Other components

- **Player**

## Connections

- Player → Touch and Story UI: uses controls (evidence: `README.md`)
- Touch and Story UI → Game Loop: calls exports (evidence: `web/pwa.js`)
- Game Loop → Input Mapping: reads input (evidence: `src/main.cpp`)
- Input Mapping → Traversal: updates movement (evidence: `src/main.cpp`)
- Game Loop → Pursuer AI: updates pursuit (evidence: `src/main.cpp`)
- Game Loop → Combat: updates combat (evidence: `src/main.cpp`)
- Combat → Projectile Combat: advances shots (evidence: `src/systems.cpp`)
- Game Loop → City Builder: builds city (evidence: `src/main.cpp`)
- Game Loop → Beacon Quests: checks progress (evidence: `src/main.cpp`)
- Beacon Quests → Boss Encounters: unlocks boss (evidence: `src/game.cpp`)
- Game Loop → XP and Skills: awards XP
- Game Loop → 3D Renderer and HUD: draws frame (evidence: `src/main.cpp`)
- Game Loop → Local Progress Save: loads and saves (evidence: `src/main.cpp`)
- Game Loop → Synth Audio: plays effects (evidence: `src/main.cpp`)
- Touch and Story UI → Synth Audio: toggles sound (evidence: `web/pwa.js`)
- Touch and Story UI → Offline PWA: registers worker (evidence: `web/pwa.js`)
- Offline PWA → Browser Cache: caches assets (evidence: `web/sw.js`)
- Traversal → Game State: updates state (evidence: `src/game.hpp`)
- Pursuer AI → Game State: updates state (evidence: `src/game.hpp`)
- Combat → Game State: updates state (evidence: `src/game.hpp`)
- 3D Renderer and HUD → Game State: renders state (evidence: `src/game.hpp`)
