# chvin/react-tetris architecture

> Architecture diagram of the GitHub repository chvin/react-tetris, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chvin/react-tetris
- Repository: https://github.com/chvin/react-tetris

## Overview

##### Project Type and Purpose
- This is a single-page client application: a React + Redux + Immutable.js implementation of the classic Tetris game.
- It includes build tooling (Webpack, Babel, ESLint), a minimal static file server (“server/”), and a “docs/” folder for published assets.
- There is no remote backend or database; instead state persistence uses localStorage and game-audio uses the browser’s Web Audio API.

##### File Structure Analysis
- Top-level build/config:
- webpack.config.js, webpack.production.config.js — build pipelines for dev and prod
- .wconfig.js, .babelrc, .eslintrc.js — linting/transpile rules
- package.json — dependencies (react, redux, immutable, webpack, etc.)
- Static assets & site:
- server/ — template index.html for serving the built app
- docs/ — generated assets published to GitHub Pages
- i18n.json — multi-language configuration
- Source code (“src/”):
- actions/ — Redux action creators
- components/ — React UI components (keyboard, matrix, guide, etc.) with dedicated styling (.less)
- containers/ — connected top-level components
- control/ — imperative game-state flows & key/touch handling
- reducers/ — Redux reducers split per feature (matrix, next, points, speed, focus, etc.)
- unit/ — utility modules (event throttling, Web Audio API handling, constants)
- store/ — store creation with redux-immutable combineReducers

##### Key Architectural Patterns & Design Principles
- Unidirectional data flow (Flux/Redux): UI dispatches actions → store → reducers → new immutable state → UI update
- Immutability: Redux store is an Immutable.js Map, ensuring cheap “===” comparisons for shouldComponentUpdate
- Separation of concerns:
→ UI layer (components)
→ State management (actions, reducers, store)
→ Side-effects/flow control (control/)
→ Utilities (unit/music.js for WebAudio, unit/event.js for input throttling)
- Responsive input: Keyboard and touch handlers co-exist, listening to keydown/touchstart, routing into the same action pipeline
- Persistence: store.subscribe → serialize full Redux state → localStorage → rehydration on init
- Build & Deployment: Webpack bundles JS & CSS, creates “docs/” for static hosting; separate dev server for hot reload

##### Main Components
A. Developer Tooling & Build Pipeline
- ESLint → Babel → Webpack (dev vs prod configs) → “docs/” output
- webpack-dev-server for local development
B. Static File Server
- server/index.html (template)
- serves JS/CSS bundle + assets
C. Client Application (Browser)
1. UI Layer (React Components)
– Presentational components under src/components (matrix display, keyboard, score, controls)
– Container components under src/containers connect to store via react-redux
2. State Management (Redux + Immutable.js)
– src/store/index.js creates store with redux-immutable combineReducers
– src/actions …… dispatch actions (e.g., MOVE_LEFT, DROP)
– src/reducers …… update slices of state immutably
– store.subscribe → localStorage persistence
3. Side-Effects & Utilities
– src/control/ for orchestrating multi-step state changes or timed loops (game loop, speed control)
– src/unit/event.js for input throttling (differentiated horizontal vs vertical rate)
– src/unit/music.js uses Web Audio API to load/play audio with low latency
4. Browser APIs & External Layers
– localStorage (state persistence)
– Web Audio API (AudioContext, bufferSource nodes)
– Visibility API (document.visibilitychange) → dispatch PAUSE/RESUME actions
– Touch/Mouse events → unify input handlers

##### Component Relationships & Data Flow
1. UI Component → dispatch(Action) → Redux Store
2. Store → pass(state) → Container (via mapStateToProps) → UI rendering (immutable props)
3. store.subscribe → serialize → localStorage
4. Control modules → dispatch sequences of actions (e.g., game start, drop timer)
5. Unit.music → Web Audio → AudioContext → Output
6. Unit.event → DOM events throttle → dispatch actions
- Unidirectional flow; separate side-effects modules off the main loop

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Deployment Layer
    subgraph "Build & Deployment" 
        direction TB
        ESLINT[".eslintrc.js"]:::infra
        BABEL[".babelrc"]:::infra
        WCFG["w.config.js"]:::infra
        WEBPACK_DEV["webpack.config.js (dev)"]:::infra
        WEBPACK_PROD["webpack.production.config.js (prod)"]:::infra
        ESLINT --> BABEL --> WEBPACK_DEV
        ESLINT --> BABEL --> WEBPACK_PROD
        WEBPACK_DEV -->|"bundle"| DOCS["docs/"]:::infra
        WEBPACK_PROD -->|"bundle"| DOCS
    end

    %% Static Server Layer
    subgraph "Static File Server" 
        direction TB
        SRV_TMPL["server/index.tmpl.html"]:::infra
        SRV_HTML["server/index.html"]:::infra
        SRV_TMPL --> SRV_HTML
        SRV_HTML -->|"serves"| CLIENT
    end

    %% Client Application Layer
    subgraph "Client Browser" 
        direction TB
        CLIENT["Browser"]:::infra

        subgraph "UI Layer" 
            direction TB
            REACT_CONTAINER["Container Components"]:::ui
            REACT_PRESENT["Presentational Components"]:::ui
            REACT_CONTAINER --> REACT_PRESENT
        end

        subgraph "State Management" 
            direction TB
            ACTIONS["Actions"]:::state
            REDUCERS["Reducers"]:::state
            STORE["Redux Store (Immutable)"]:::state
            ACTIONS --> STORE
            STORE --> REDUCERS
            REDUCERS --> STORE
            STORE -->|"mapStateToProps"| REACT_CONTAINER
            REACT_CONTAINER -->|"dispatch"| ACTIONS
        end

        subgraph "Side-Effects & Utilities" 
            direction TB
            CONTROL["Control Modules"]:::util
            EVENT["Input Throttler"]:::util
            MUSIC_UNIT["Music Player"]:::util
            CONTROL --> ACTIONS
            EVENT --> ACTIONS
            MUSIC_UNIT -->|"AudioContext"| AUDIO_API
        end

        subgraph "Browser APIs & Persistence" 
            direction TB
            AUDIO_API("Web Audio API"):::api
            VISIBILITY("Visibility API"):::api
            LOCSTRG(("localStorage")):::api
            STORE -->|"subscribe"| LOCSTRG
            VISIBILITY -->|"dispatch PAUSE/RESUME"| ACTIONS
            AUDIO_API -->|"play"| CLIENT
        end

        CLIENT -->|"UI render"| REACT_PRESENT
        REACT_PRESENT -->|"events"| EVENT
        CLIENT -->|"keydown/touch"| EVENT
    end

    %% Published Assets
    DOCS -->|"index.html"| DOCS_HTML["docs/index.html"]:::infra
    DOCS -->|"app js"| DOCS_JS["docs/app-1.0.1.js"]:::infra
    DOCS -->|"css"| DOCS_CSS["docs/css-1.0.1.css"]:::infra
    DOCS -->|"loader css"| DOCS_LCSS["docs/loader.css"]:::infra

    %% Internationalization
    I18N["i18n.json"]:::infra
    CLIENT --> I18N

    %% Entry Point
    ENTRY["src/index.js"]:::infra
    ENTRY --> STORE
    ENTRY --> REACT_CONTAINER

    %% Styles
    classDef ui fill:#ccf,stroke:#333,stroke-width:1px
    classDef state fill:#cfc,stroke:#333,stroke-width:1px
    classDef util fill:#fc9,stroke:#333,stroke-width:1px
    classDef infra fill:#ddd,stroke:#333,stroke-width:1px
    classDef api fill:#eee,stroke:#333,stroke-width:1px

    %% Click Events
    click ESLINT "https://github.com/chvin/react-tetris/blob/master/.eslintrc.js"
    click BABEL "https://github.com/chvin/react-tetris/blob/master/.babelrc"
    click WCFG "https://github.com/chvin/react-tetris/blob/master/w.config.js"
    click WEBPACK_DEV "https://github.com/chvin/react-tetris/blob/master/webpack.config.js"
    click WEBPACK_PROD "https://github.com/chvin/react-tetris/blob/master/webpack.production.config.js"
    click SRV_TMPL "https://github.com/chvin/react-tetris/blob/master/server/index.tmpl.html"
    click SRV_HTML "https://github.com/chvin/react-tetris/blob/master/server/index.html"
    click DOCS_HTML "https://github.com/chvin/react-tetris/blob/master/docs/index.html"
    click DOCS_JS "https://github.com/chvin/react-tetris/blob/master/docs/app-1.0.1.js"
    click DOCS_CSS "https://github.com/chvin/react-tetris/blob/master/docs/css-1.0.1.css"
    click DOCS_LCSS "https://github.com/chvin/react-tetris/blob/master/docs/loader.css"
    click I18N "https://github.com/chvin/react-tetris/blob/master/i18n.json"
    click ENTRY "https://github.com/chvin/react-tetris/blob/master/src/index.js"
```
