# trimpham98/rogue-tank-royale architecture

> Architecture diagram of the GitHub repository trimpham98/rogue-tank-royale, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trimpham98/rogue-tank-royale
- Repository: https://github.com/trimpham98/rogue-tank-royale

## Overview

##### Project type and purpose
- Tank Rogue is a browser-based single-page application (SPA) built with React, TypeScript, and Three.js.
- Its purpose is to render a 3D, roguelike tank game, manage game state, and provide UI controls and feedback.

##### File structure
- Top-level: package.json, vite.config.ts, tsconfig, README.md → build & config.
- public/ → static assets (images, sounds).
- src/
- components/ → all React UI & scene components (StartScreen, GameScene, GameUI, etc.)
- hooks/ → custom React hooks (keyboard, weapon selection)
- models/ → TypeScript classes for game objects (Tank, EnemyTank, Projectiles…)
- utils/ → pure functions & managers (levelGenerator, respawnManager, sound, debug)
- App.tsx, main.tsx → root of the React app and scene setup

##### README for insights
- Centralized state with Zustand (game state, stats, level)
- Rendering via React Three Fiber + Drei
- Procedural level generation, power-ups, enemies, UI overlay

a. Main components to illustrate:
1. Browser / SPA Host
2. React App Layer
- Entry (main.tsx, App.tsx)
- Component Tree
3. Input Layer (hooks/useKeyboardControls)
4. State Management (Zustand store)
5. Game Logic Layer
- Models (Tank, Projectile, EnemyTank, SafeZone…)
- Utils (levelGenerator, respawnManager, gameState helpers)
6. Rendering Engine
- React Three Fiber (bridge to Three.js)
- Three.js core
7. Assets & Media
- public/assets (images, audio)
8. Build & Tooling
- Vite (dev server, bundler)
- TypeScript compiler

b. Relationships and interactions:
- Input Layer → emits player commands → updates Zustand Store
- Zustand Store → notifies subscribed React components & hooks
- Game Logic Layer reads/writes from Store → updates object states (positions, health)
- Rendering Engine consumes object states → draws/update 3D scene
- Asset Layer provides media to Rendering & UI (models, textures, sounds)
- Build & Tooling supplies code hot-reload and bundles for deployment

c. Architectural patterns & principles:
- Unidirectional data flow (React + Zustand)
- Component-based decomposition (UI / scene / utility)
- Separation of concerns: Input → State → Logic → Rendering → UI
- Declarative rendering via React Three Fiber

d. Key technologies/frameworks to label:
- React, ReactDOM
- React Three Fiber, Three.js, Drei
- Zustand
- Vite
- TypeScript

##### Final recommendation
- External libraries around the periphery
- Data flows and subscription flows for Zustand
- Asynchronous processes (procedural generation, sound loading)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser / Host
    Browser["Browser / SPA Host\n(index.html)"]:::external

    %% React App Layer
    subgraph "React App Layer"
        Entry["App Entry\n(src/main.tsx, src/App.tsx)"]:::frontend
    end

    %% Input Layer
    subgraph "Input Layer"
        Keyboard["Keyboard Controls Hook\n(useKeyboardControls)"]:::input
        WeaponHook["Weapon Selection Hook\n(useWeaponSelection)"]:::input
    end

    %% State Management
    Store["Zustand Store Helpers\n(gameState)"]:::state

    %% Game Logic Layer
    subgraph "Game Logic Layer"
        Models["Models\n(src/models/)"]:::logic
        Utils["Utils\n(levelGenerator, respawnManager, tankStats, weaponTracking, weapons)"]:::logic
        Debug["Debug & Diagnostics\n(debug)"]:::logic
        Sound["Sound Management\n(sound)"]:::logic
    end

    %% Rendering Engine
    subgraph "Rendering Engine"
        R3F["React Three Fiber"]:::render
        ThreeJS["Three.js Core"]:::render
        Scene["GameScene Canvas\n(GameScene.tsx)"]:::render
    end

    %% UI Layer
    subgraph "UI Layer"
        GameUI["Game UI Overlay\n(GameUI.tsx)"]:::ui
        Start["Start Screen\n(StartScreen.tsx)"]:::ui
        WeaponUI["Weapon Selection UI\n(WeaponSelection.tsx)"]:::ui
        StatUI["Stat Upgrade UI\n(StatUpgradeUI.tsx)"]:::ui
        Tactical["Tactical Display\n(TacticalDisplay.tsx)"]:::ui
        Joysticks["Mobile Joysticks\n(MobileJoysticks.tsx)"]:::ui
        Wireframe["Tank Wireframe Display\n(TankWireframeDisplay.tsx)"]:::ui
    end

    %% Assets & Media
    Assets["Assets & Media\n(public/assets/)"]:::assets

    %% Build & Tooling
    Tooling["Build & Tooling\n(package.json, vite.config.ts, tsconfig*)"]:::tooling

    %% Flows
    Browser --> Entry
    Entry --> Keyboard
    Entry --> WeaponHook
    Keyboard -->|emits commands| Store
    WeaponHook -->|emits selection| Store
    Store -->|subscribe| GameUI
    Store -->|subscribe| Scene
    Store -->|subscribe| Models
    Store -->|subscribe| Utils
    Models -->|update state| Store
    Utils -->|update state| Store
    Store -->|state data| R3F
    R3F -->|renders| ThreeJS
    ThreeJS --> Scene
    Assets --> Scene
    Assets --> GameUI
    Tooling -.-> Entry

    %% Click Events
    click Browser "https://github.com/trimpham98/rogue-tank-royale/blob/main/index.html"
    click Entry "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/main.tsx"
    click Entry "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/App.tsx"
    click Keyboard "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/hooks/useKeyboardControls.ts"
    click WeaponHook "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/hooks/useWeaponSelection.ts"
    click Store "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/utils/gameState.ts"
    click Models "https://github.com/trimpham98/rogue-tank-royale/tree/main/src/models/"
    click Utils "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/utils/levelGenerator.ts"
    click Utils "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/utils/respawnManager.ts"
    click Utils "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/utils/tankStats.ts"
    click Utils "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/utils/weaponTracking.ts"
    click Utils "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/utils/weapons.ts"
    click Debug "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/utils/debug.ts"
    click Sound "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/utils/sound.ts"
    click Scene "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/components/GameScene.tsx"
    click GameUI "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/components/GameUI.tsx"
    click Start "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/components/StartScreen.tsx"
    click WeaponUI "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/components/WeaponSelection.tsx"
    click StatUI "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/components/StatUpgradeUI.tsx"
    click Tactical "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/components/TacticalDisplay.tsx"
    click Joysticks "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/components/MobileJoysticks.tsx"
    click Wireframe "https://github.com/trimpham98/rogue-tank-royale/blob/main/src/components/TankWireframeDisplay.tsx"
    click Tooling "https://github.com/trimpham98/rogue-tank-royale/blob/main/package.json"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef input fill:#E0F7FA,stroke:#00796B,color:#004D40;
    classDef state fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20;
    classDef logic fill:#FFF3E0,stroke:#EF6C00,color:#E65100;
    classDef render fill:#F3E5F5,stroke:#8E24AA,color:#6A1B9A;
    classDef ui fill:#E3F2FD,stroke:#1E88E5,color:#0D47A1;
    classDef assets fill:#EFEBE9,stroke:#5D4037,color:#3E2723;
    classDef tooling fill:#ECEFF1,stroke:#607D8B,color:#37474F;
    classDef external fill:#FFFFFF,stroke:#000000,color:#000000,stroke-dasharray: 5 5;
```
