# zeroxm/pokemon-roulette architecture

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

- Interactive diagram: https://gitdiagram.com/zeroxm/pokemon-roulette
- Repository: https://github.com/zeroxm/pokemon-roulette

## Overview

1. This is a client-side Angular 19 single-page game. The app shell lives in `app.component`, with route setup in `app.routes.ts` and global configuration in `app.config.ts`. There is no backend in the repo; gameplay, content, and state management are handled in the browser.

2. The top-level experience is split into route-like screens: the main game, trainer-team management, items, coffee, settings, credits, and a not-found screen. The app uses reusable button components such as the main game button, restart button, settings button, coffee button, and credits button to move between these areas.

3. The core gameplay loop is centered in `src/app/main-game`. That subtree contains the main game container plus a roulette system that drives most game events. The `wheel` component is the spinning interaction surface, while `roulette-container` selects and renders a specific roulette scenario.

4. The roulette system is the main architectural boundary. Each roulette component represents a different Pokémon-themed event or encounter: battles, item discovery, evolution checks, starter selection, fishing, fossils, caves, legendary encounters, paradox catches, gym/champion/elite-four battles, Team Rocket, shiny encounters, trades, and special story sequences. These are mostly isolated presentation/interaction modules that plug into the same container.

5. Most roulettes are data-driven from static tables in the repo rather than remote services. Generation-specific datasets such as `pokemon-by-generation.ts`, `starter-by-generation.ts`, `champion-by-generation.ts`, and similar files provide the content each roulette needs. This makes generation, region, and event selection a key content boundary in the design.

6. The domain logic is concentrated in `src/app/services`. These services encapsulate game rules and shared data such as Pokémon, Pokédex, generation, items, evolutions, type matchups, trainer sprites/forms, badges, rare candy behavior, and mega-stone handling. In the diagram, these services sit between UI components and the underlying static datasets/models.

7. Game state is managed separately from the UI. `game-state-service`, `settings-service`, `badges-service`, `pokedex-service`, and related services likely own the persistent browser-side progress and preferences that multiple screens need. This is the main cross-cutting state layer that ties gameplay, collection screens, and settings together.

8. Audio and feedback are part of the gameplay architecture. The `public/` folder contains sound effects such as item found, PC login/logout, clicking, and Mega Evolution audio. `sound-fx-service` is the orchestration point for these assets, so sound is triggered by gameplay events rather than embedded directly in each component.

9. Internationalization and appearance are first-class concerns. Translation bundles live in `src/assets/i18n` for several languages, and the dark-mode/theme subsystem is implemented under `services/dark-mode-service` and `services/theme-service`, with matching UI in `settings/dark-mode-toggle` and `settings/theme-selector`. These are presentation-layer concerns that influence many screens.

10. The trainer and collection features form a second major user-facing subsystem outside the main game. `trainer-team` contains Pokédex, badges, and storage-PC views, backed by Pokémon/trainer data services. This area is distinct from the roulette loop: it is where accumulated game progress is inspected and managed.

11. Shared types and constants keep the content model consistent. The `interfaces/` folder defines domain entities like Pokémon, items, gym leaders, forms, languages, wheel items, and type matchups, while `constants/` holds fixed IDs and lookup values. This is the schema layer used by the services and roulette components.

12. Build and delivery are standard Angular CLI/GitHub Pages. The repository includes a GitHub Actions workflow, production/environment files, and `angular.json`. The README shows deployment to GitHub Pages with a `/pokemon-roulette/` base href, which means the app is intended to run as a static hosted SPA.

Main entry points: [`src/app/app.routes.ts`](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/app.routes.ts) (Routes), [`src/app/main-game/main-game.component.ts`](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/main-game/main-game.component.ts) (Main game), [`src/app/main-game/roulette-container/roulette-container.component.ts`](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/main-game/roulette-container/roulette-container.component.ts) (Roulette hub), [`src/app/trainer-team/trainer-team.component.ts`](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/trainer-team/trainer-team.component.ts) (Trainer team)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app_shell["App shell"]
  node_node_app_component["App shell<br/>Angular root<br/>[app.component.ts]"]
  node_node_app_routes["Routes<br/>Router config<br/>[app.routes.ts]"]
  node_node_app_config["App config<br/>Angular config<br/>[app.config.ts]"]
  node_node_settings["Settings<br/>Preferences screen"]
  node_node_credits["Credits<br/>Info screen"]
end

subgraph group_group_main_game["Main game"]
  node_node_main_game["Main game<br/>Game screen"]
  node_node_roulette_container["Roulette hub<br/>Event router"]
  node_node_wheel(("Wheel<br/>Spin UI<br/>[wheel.component.ts]"))
  node_node_start_main_adventure["Adventure start<br/>Scenario"]
  node_node_core_roulettes["Core roulettes<br/>Event modules"]
  node_node_aux_roulettes["Aux roulettes<br/>Event modules"]
end

subgraph group_group_collection["Collection views"]
  node_node_trainer_team["Trainer team<br/>Collection screen"]
  node_node_pokedex_view["Pokédex<br/>Collection view"]
  node_node_badges_view["Badges<br/>Collection view"]
  node_node_storage_pc["Storage PC<br/>Collection view"]
end

subgraph group_group_services["Services"]
  node_node_services_state[("Game state<br/>Persistent state")]
  node_node_services_rules["Domain rules<br/>Rules services<br/>[pokemon.service.ts]"]
  node_node_services_progress["Progress services<br/>Collection services<br/>[pokedex.service.ts]"]
  node_node_services_fx["Audio FX<br/>Feedback service"]
  node_node_services_theme["Theme layer<br/>Presentation services<br/>[theme.service.ts]"]
end

subgraph group_group_content["Content data"]
  node_node_static_tables["Static tables<br/>Content data"]
end

node_node_app_component -->|"hosts"| node_node_app_routes
node_node_app_component -->|"bootstraps"| node_node_app_config
node_node_app_routes -->|"routes to"| node_node_main_game
node_node_app_routes -->|"routes to"| node_node_trainer_team
node_node_app_routes -->|"routes to"| node_node_settings
node_node_app_routes -->|"routes to"| node_node_credits
node_node_main_game -->|"contains"| node_node_roulette_container
node_node_main_game -->|"uses"| node_node_wheel
node_node_roulette_container -->|"mounts"| node_node_start_main_adventure
node_node_roulette_container -->|"mounts"| node_node_core_roulettes
node_node_roulette_container -->|"mounts"| node_node_aux_roulettes
node_node_roulette_container -->|"reads"| node_node_static_tables
node_node_core_roulettes -->|"uses"| node_node_services_rules
node_node_aux_roulettes -->|"uses"| node_node_services_rules
node_node_aux_roulettes -->|"triggers"| node_node_services_fx
node_node_trainer_team -->|"contains"| node_node_pokedex_view
node_node_trainer_team -->|"contains"| node_node_badges_view
node_node_trainer_team -->|"contains"| node_node_storage_pc
node_node_trainer_team -->|"uses"| node_node_services_progress
node_node_settings -->|"uses"| node_node_services_theme
node_node_settings -->|"uses"| node_node_services_state
node_node_main_game -->|"uses"| node_node_services_state
node_node_main_game -->|"uses"| node_node_services_rules
node_node_services_progress -->|"persists via"| node_node_services_state
node_node_services_rules -->|"indexes"| node_node_static_tables
node_node_services_fx -->|"supports"| node_node_main_game
node_node_app_routes -->|"shares state"| node_node_services_state

click node_node_app_component "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/app.component.ts"
click node_node_app_routes "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/app.routes.ts"
click node_node_app_config "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/app.config.ts"
click node_node_main_game "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/main-game/main-game.component.ts"
click node_node_roulette_container "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/main-game/roulette-container/roulette-container.component.ts"
click node_node_wheel "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/wheel/wheel.component.ts"
click node_node_start_main_adventure "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/main-game/roulette-container/roulettes/start-adventure-roulette/start-adventure-roulette.component.ts"
click node_node_core_roulettes "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/main-game/roulette-container/roulettes/main-adventure-roulette/main-adventure-roulette.component.ts"
click node_node_aux_roulettes "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/main-game/roulette-container/roulettes/find-item-roulette/find-item-roulette.component.ts"
click node_node_trainer_team "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/trainer-team/trainer-team.component.ts"
click node_node_pokedex_view "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/trainer-team/pokedex/pokedex.component.ts"
click node_node_badges_view "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/trainer-team/badges/badges.component.ts"
click node_node_storage_pc "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/trainer-team/storage-pc/storage-pc.component.ts"
click node_node_settings "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/settings/settings.component.ts"
click node_node_credits "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/credits/credits.component.ts"
click node_node_services_state "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/services/game-state-service/game-state.service.ts"
click node_node_services_rules "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/services/pokemon-service/pokemon.service.ts"
click node_node_services_progress "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/services/pokedex-service/pokedex.service.ts"
click node_node_services_fx "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/services/sound-fx-service/sound-fx.service.ts"
click node_node_services_theme "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/services/theme-service/theme.service.ts"
click node_node_static_tables "https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/main-game/roulette-container/roulettes/pokemon-from-generation-roulette/pokemon-by-generation.ts"

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_node_app_component,node_node_app_routes,node_node_app_config,node_node_settings,node_node_credits toneBlue
class node_node_main_game,node_node_roulette_container,node_node_wheel,node_node_start_main_adventure,node_node_core_roulettes,node_node_aux_roulettes toneAmber
class node_node_trainer_team,node_node_pokedex_view,node_node_badges_view,node_node_storage_pc toneMint
class node_node_services_state,node_node_services_rules,node_node_services_progress,node_node_services_fx,node_node_services_theme toneRose
class node_node_static_tables toneIndigo
```

## Components

### App shell

Routing, top-level screens, and shared navigation

- [App shell](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/app.component.ts): Angular root · Top-level SPA shell that hosts routes and global layout · `src/app/app.component.ts`
- [Routes](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/app.routes.ts): Router config · Route map for game, collection, settings, credits, and fallback screens · `src/app/app.routes.ts`
- [App config](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/app.config.ts): Angular config · Global application providers and bootstrap configuration · `src/app/app.config.ts`
- [Settings](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/settings/settings.component.ts): Preferences screen · Theme, dark mode, and app preferences · `src/app/settings/settings.component.ts`
- [Credits](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/credits/credits.component.ts): Info screen · Attribution and project credits screen · `src/app/credits/credits.component.ts`

### Main game

Core roulette loop and event presentation

- [Main game](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/main-game/main-game.component.ts): Game screen · Primary gameplay screen and container for the roulette loop · `src/app/main-game/main-game.component.ts`
- [Roulette hub](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/main-game/roulette-container/roulette-container.component.ts): Event router · Selects and mounts the active roulette scenario · `src/app/main-game/roulette-container/roulette-container.component.ts`
- [Wheel](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/wheel/wheel.component.ts): Spin UI · Spinning interaction surface that drives game events · `src/app/wheel/wheel.component.ts`
- [Adventure start](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/main-game/roulette-container/roulettes/start-adventure-roulette/start-adventure-roulette.component.ts): Scenario · Entry flow that kicks off a new run and advances into gameplay · `src/app/main-game/roulette-container/roulettes/start-adventure-roulette/start-adventure-roulette.component.ts`
- [Core roulettes](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/main-game/roulette-container/roulettes/main-adventure-roulette/main-adventure-roulette.component.ts): Event modules · Representative event modules for battles, encounters, and special sequences · `src/app/main-game/roulette-container/roulettes/main-adventure-roulette/main-adventure-roulette.component.ts`
- [Aux roulettes](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/main-game/roulette-container/roulettes/find-item-roulette/find-item-roulette.component.ts): Event modules · Supporting event modules for items, evolution, fishing, caves, and trades · `src/app/main-game/roulette-container/roulettes/find-item-roulette/find-item-roulette.component.ts`

### Collection views

Trainer-team and progress management screens

- [Trainer team](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/trainer-team/trainer-team.component.ts): Collection screen · Hub for Pokédex, badges, and storage-PC management · `src/app/trainer-team/trainer-team.component.ts`
- [Pokédex](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/trainer-team/pokedex/pokedex.component.ts): Collection view · Pokédex browsing and detail experience · `src/app/trainer-team/pokedex/pokedex.component.ts`
- [Badges](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/trainer-team/badges/badges.component.ts): Collection view · Badge progress and earned achievements · `src/app/trainer-team/badges/badges.component.ts`
- [Storage PC](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/trainer-team/storage-pc/storage-pc.component.ts): Collection view · Stored Pokémon and party-adjacent management · `src/app/trainer-team/storage-pc/storage-pc.component.ts`

### Services

State, rules, audio, theme, and shared domain logic

- [Game state](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/services/game-state-service/game-state.service.ts): Persistent state · Browser-side progress and cross-screen game state · `src/app/services/game-state-service/game-state.service.ts`
- [Domain rules](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/services/pokemon-service/pokemon.service.ts): Rules services · Pokémon, items, evolutions, generation, type matchups, and related gameplay logic · `src/app/services/pokemon-service/pokemon.service.ts`
- [Progress services](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/services/pokedex-service/pokedex.service.ts): Collection services · Pokédex, badges, settings, and trainer data services · `src/app/services/pokedex-service/pokedex.service.ts`
- [Audio FX](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/services/sound-fx-service/sound-fx.service.ts): Feedback service · Sound effect orchestration for gameplay-triggered audio · `src/app/services/sound-fx-service/sound-fx.service.ts`
- [Theme layer](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/services/theme-service/theme.service.ts): Presentation services · Dark mode and theme selection services · `src/app/services/theme-service/theme.service.ts`

### Content data

Static generation- and domain-specific tables

- [Static tables](https://github.com/zeroxm/pokemon-roulette/blob/main/src/app/main-game/roulette-container/roulettes/pokemon-from-generation-roulette/pokemon-by-generation.ts): Content data · Generation-based Pokémon, starters, champions, gyms, caves, fossils, and legendary data · `src/app/main-game/roulette-container/roulettes/pokemon-from-generation-roulette/pokemon-by-generation.ts`

## Connections

- App shell → Routes: hosts · The shell renders routed screens
- App shell → App config: bootstraps · Root configuration is applied at startup
- Routes → Main game: routes to · Primary gameplay screen
- Routes → Trainer team: routes to · Trainer and collection screen
- Routes → Settings: routes to · Settings screen
- Routes → Credits: routes to · Credits screen
- Main game → Roulette hub: contains · Main game delegates event selection to roulette hub
- Main game → Wheel: uses · Wheel drives the central interaction loop
- Roulette hub → Adventure start: mounts · Entry scenario for a new adventure
- Roulette hub → Core roulettes: mounts · Battle and encounter scenarios
- Roulette hub → Aux roulettes: mounts · Item, evolution, travel, and trade scenarios
- Roulette hub → Static tables: reads · Roulette scenarios are fed by static content tables
- Core roulettes → Domain rules: uses · Event outcomes rely on shared domain logic
- Aux roulettes → Domain rules: uses · Support events consult gameplay rules and data
- Aux roulettes → Audio FX: triggers · Events emit sound feedback through the audio service
- Trainer team → Pokédex: contains · Collection browsing subview
- Trainer team → Badges: contains · Badge progress subview
- Trainer team → Storage PC: contains · Storage management subview
- Trainer team → Progress services: uses · Collection screens are backed by persistence and progress services
- Settings → Theme layer: uses · Theme and dark-mode controls
- Settings → Game state: uses · Preferences are persisted in browser state
- Main game → Game state: uses · Gameplay reads and updates persistent state
- Main game → Domain rules: uses · Game flow depends on shared rules services
- Progress services → Game state: persists via · Progress services store cross-screen data
- Domain rules → Static tables: indexes · Rules layer consumes the static content model
- Audio FX → Main game: supports · Audio responds to gameplay events
- Routes → Game state: shares state · Routes and screens rely on the same browser-side progress