# gangsonic/bug_hunters architecture

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

- Interactive diagram: https://gitdiagram.com/gangsonic/bug_hunters
- Repository: https://github.com/gangsonic/bug_hunters

## Overview

Bug Hunters is an educational 2D debugging game. The player starts, selects one of four cases across two worlds, observes an anomaly, records a hypothesis, chooses a repair, runs it, and sees the outcome and case record. The mission screen coordinates case simulation, state transitions, hints, and progress; the app shell routes between screens and overlays. The README also documents help/tutorial, BugDex, settings, saved progress, audio, and pilot mode. Some feature implementations were not sampled, so their internal links are omitted where source evidence is unavailable.

Main entry points: [`src/app/App.tsx`](https://github.com/gangsonic/bug_hunters/blob/main/src/app/App.tsx) (App shell), [`src/features/mision/components/PantallaMision.tsx`](https://github.com/gangsonic/bug_hunters/blob/main/src/features/mision/components/PantallaMision.tsx) (Mission screen), [`src/features/mision`](https://github.com/gangsonic/bug_hunters/tree/main/src/features/mision) (Mission runtime), [`src/features/seleccion/components/Seleccion.tsx`](https://github.com/gangsonic/bug_hunters/blob/main/src/features/seleccion/components/Seleccion.tsx) (Case selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shell["App shell"]
  node_app["App shell<br/>[App.tsx]"]
  node_navigation["Navigation<br/>[navegacionStore.ts]"]
end

subgraph group_game["Case gameplay"]
  node_start["Start screen<br/>[Inicio.tsx]"]
  node_selection["Case selection<br/>[Seleccion.tsx]"]
  node_mission["Mission screen<br/>[PantallaMision.tsx]"]
  node_missionlogic["Mission runtime"]
  node_cases["Case simulations"]
  node_result["Results"]
  node_bugdex["BugDex<br/>[BugDex.tsx]"]
end

subgraph group_support["Player support"]
  node_help["Help and tutorial"]
  node_settings["Settings"]
  node_audio["Music playback"]
  node_pilot["Pilot mode"]
end

subgraph group_state["Settings and state"]
  node_progress[("Saved progress<br/>[progresoStore.ts]")]
  node_missionstate["Navigation state<br/>[navegacionStore.ts]"]
end

subgraph group_shared["Shared interface"]
  node_sharedui["Shared UI"]
  node_icon["Icon rendering<br/>[Icono.tsx]"]
end

node_player(("Player"))

node_player -->|"starts game"| node_app
node_app -->|"reads route state"| node_navigation
node_app -->|"shows screen"| node_start
node_app -->|"routes to"| node_selection
node_app -->|"routes to"| node_mission
node_app -->|"routes to"| node_result
node_app -->|"shows screen"| node_bugdex
node_app -->|"opens help"| node_help
node_app -->|"opens settings"| node_settings
node_app -->|"starts music"| node_audio
node_start -->|"starts case flow"| node_selection
node_selection -->|"opens selected case"| node_mission
node_mission -->|"uses mission runtime"| node_missionlogic
node_mission -->|"loads case"| node_cases
node_missionlogic -->|"evaluates repair"| node_cases
node_missionlogic -->|"marks resolved"| node_progress
node_mission -->|"signals resolved"| node_result
node_result -->|"opens case record"| node_bugdex
node_missionlogic -->|"records attempts"| node_pilot
node_help -->|"offers case link"| node_selection
node_settings -->|"controls music"| node_audio
node_app -->|"renders notice"| node_sharedui
node_sharedui -->|"uses icons"| node_icon

click node_app "https://github.com/gangsonic/bug_hunters/blob/main/src/app/App.tsx"
click node_navigation "https://github.com/gangsonic/bug_hunters/blob/main/src/app/navegacion/navegacionStore.ts"
click node_start "https://github.com/gangsonic/bug_hunters/blob/main/src/features/inicio/components/Inicio.tsx"
click node_selection "https://github.com/gangsonic/bug_hunters/blob/main/src/features/seleccion/components/Seleccion.tsx"
click node_mission "https://github.com/gangsonic/bug_hunters/blob/main/src/features/mision/components/PantallaMision.tsx"
click node_missionlogic "https://github.com/gangsonic/bug_hunters/tree/main/src/features/mision"
click node_cases "https://github.com/gangsonic/bug_hunters/tree/main/src/features/expedientes"
click node_result "https://github.com/gangsonic/bug_hunters/tree/main/src/features/resultado"
click node_bugdex "https://github.com/gangsonic/bug_hunters/blob/main/src/features/bugdex/components/BugDex.tsx"
click node_help "https://github.com/gangsonic/bug_hunters/tree/main/src/features/ayuda"
click node_settings "https://github.com/gangsonic/bug_hunters/tree/main/src/features/configuracion"
click node_audio "https://github.com/gangsonic/bug_hunters/tree/main/src/features/audio"
click node_pilot "https://github.com/gangsonic/bug_hunters/tree/main/src/features/piloto"
click node_progress "https://github.com/gangsonic/bug_hunters/blob/main/src/features/progreso/store/progresoStore.ts"
click node_missionstate "https://github.com/gangsonic/bug_hunters/blob/main/src/app/navegacion/navegacionStore.ts"
click node_sharedui "https://github.com/gangsonic/bug_hunters/tree/main/src/shared/ui"
click node_icon "https://github.com/gangsonic/bug_hunters/blob/main/src/shared/ui/Icono.tsx"

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_navigation toneBlue
class node_start,node_selection,node_mission,node_missionlogic,node_cases,node_result,node_bugdex toneAmber
class node_help,node_settings,node_audio,node_pilot toneMint
class node_progress,node_missionstate toneRose
class node_sharedui,node_icon,node_player toneIndigo
```

## Components

### App shell

- [App shell](https://github.com/gangsonic/bug_hunters/blob/main/src/app/App.tsx): `src/app/App.tsx`
- [Navigation](https://github.com/gangsonic/bug_hunters/blob/main/src/app/navegacion/navegacionStore.ts): `src/app/navegacion/navegacionStore.ts`

### Case gameplay

- [Start screen](https://github.com/gangsonic/bug_hunters/blob/main/src/features/inicio/components/Inicio.tsx): `src/features/inicio/components/Inicio.tsx`
- [Case selection](https://github.com/gangsonic/bug_hunters/blob/main/src/features/seleccion/components/Seleccion.tsx): `src/features/seleccion/components/Seleccion.tsx`
- [Mission screen](https://github.com/gangsonic/bug_hunters/blob/main/src/features/mision/components/PantallaMision.tsx): `src/features/mision/components/PantallaMision.tsx`
- [Mission runtime](https://github.com/gangsonic/bug_hunters/tree/main/src/features/mision): `src/features/mision`
- [Case simulations](https://github.com/gangsonic/bug_hunters/tree/main/src/features/expedientes): `src/features/expedientes`
- [Results](https://github.com/gangsonic/bug_hunters/tree/main/src/features/resultado): `src/features/resultado`
- [BugDex](https://github.com/gangsonic/bug_hunters/blob/main/src/features/bugdex/components/BugDex.tsx): `src/features/bugdex/components/BugDex.tsx`

### Player support

- [Help and tutorial](https://github.com/gangsonic/bug_hunters/tree/main/src/features/ayuda): `src/features/ayuda`
- [Settings](https://github.com/gangsonic/bug_hunters/tree/main/src/features/configuracion): `src/features/configuracion`
- [Music playback](https://github.com/gangsonic/bug_hunters/tree/main/src/features/audio): `src/features/audio`
- [Pilot mode](https://github.com/gangsonic/bug_hunters/tree/main/src/features/piloto): `src/features/piloto`

### Settings and state

- [Saved progress](https://github.com/gangsonic/bug_hunters/blob/main/src/features/progreso/store/progresoStore.ts): `src/features/progreso/store/progresoStore.ts`
- [Navigation state](https://github.com/gangsonic/bug_hunters/blob/main/src/app/navegacion/navegacionStore.ts): `src/app/navegacion/navegacionStore.ts`

### Shared interface

- [Shared UI](https://github.com/gangsonic/bug_hunters/tree/main/src/shared/ui): `src/shared/ui`
- [Icon rendering](https://github.com/gangsonic/bug_hunters/blob/main/src/shared/ui/Icono.tsx): `src/shared/ui/Icono.tsx`

### Other components

- **Player**

## Connections

- Player → App shell: starts game (evidence: `src/app/App.tsx`)
- App shell → Navigation: reads route state (evidence: `src/app/App.tsx`)
- App shell → Start screen: shows screen (evidence: `src/app/App.tsx`)
- App shell → Case selection: routes to (evidence: `src/app/App.tsx`)
- App shell → Mission screen: routes to (evidence: `src/app/App.tsx`)
- App shell → Results: routes to (evidence: `src/app/App.tsx`)
- App shell → BugDex: shows screen (evidence: `src/app/App.tsx`)
- App shell → Help and tutorial: opens help (evidence: `src/app/App.tsx`)
- App shell → Settings: opens settings (evidence: `src/app/App.tsx`)
- App shell → Music playback: starts music (evidence: `src/app/App.tsx`)
- Start screen → Case selection: starts case flow
- Case selection → Mission screen: opens selected case
- Mission screen → Mission runtime: uses mission runtime (evidence: `src/features/mision/components/PantallaMision.tsx`)
- Mission screen → Case simulations: loads case (evidence: `src/features/mision/components/PantallaMision.tsx`)
- Mission runtime → Case simulations: evaluates repair (evidence: `src/features/mision/hooks/useMision.ts`)
- Mission runtime → Saved progress: marks resolved (evidence: `src/features/mision/hooks/useMision.ts`)
- Mission screen → Results: signals resolved
- Results → BugDex: opens case record
- Mission runtime → Pilot mode: records attempts (evidence: `src/features/mision/hooks/useMision.ts`)
- Help and tutorial → Case selection: offers case link
- Settings → Music playback: controls music (evidence: `src/features/audio/useMusica.ts`)
- App shell → Shared UI: renders notice (evidence: `src/app/App.tsx`)
- Shared UI → Icon rendering: uses icons (evidence: `src/shared/ui/Boton.tsx`)
