# noahm/ddrcarddraw architecture

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

- Interactive diagram: https://gitdiagram.com/noahm/ddrcarddraw
- Repository: https://github.com/noahm/ddrcarddraw

## Overview

##### Main components of the system
- Frontend (User Interface)
- All files under the src/ directory form the core of the React application.
- Subcomponents/directories such as controls, eligible-charts, song-card, song-search, tournament-mode, etc.
- Assets like jacket images and internationalization files (i18n.json) that support styling and localization.
- Incorporate state management (e.g., Zustand-related files) and common hooks that manage component state.
- Data Management & Import Pipelines
- The scripts/ directory contains a series of Node scripts that import and update song data from different sources (e.g., DDR, ITG, Pump it Up, SMX). These include both data ingestion and scraping tools.
- The JSON song data stored in src/songs indicates the persistence of game data.
- Build & Deployment Infrastructure
- Files like webpack.config.js, tsconfig.json, package.json, and .yarn files define build configuration, dependency management, and bundling.
- GitHub workflows (in .github/workflows) illustrate the CI/CD process.
- Documentation & Community
- The docs/ folder along with CONTRIBUTING and networking guides support the project’s broader community interaction although these are not part of the runtime design.

##### Relationships and Data Flow
- The build and deployment system (Yarn, Webpack, GitHub actions) is responsible for compiling the app, running validations (such as the JSON format check via “yarn validate:json”), and producing the final offline-app package.

##### Architectural Patterns and Principles
- Component-based architecture in the React app – each directory under src/ (for example, controls, song-card, tournament-mode) represents a distinct UI module.
- Separation of concerns – clear division between the UI (React front end) and the data ingestion workflows (scripts/).
- State management using a central store (Zustand) to share state between components, emphasizing maintainability.
- The project also leverages automated CI/CD pipelines for testing and deployment, as indicated by workflow configurations in .github/workflows.

##### Relevant Technologies and Frameworks
- React (with TypeScript) for the UI.
- Zustand for state management.
- Node.js (with Yarn as package manager) for scripting and build processes.
- Webpack for bundling the application.
- Various libraries to support internationalization, styling (CSS files), and possibly data validation (the JSON schema file).
- GitHub Actions for CI/CD integration.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend UI and related subcomponents
    subgraph "Frontend UI (React Application)"
        FE["React App (src/)"]:::frontendColor
        FE_C["Controls (src/controls)"]:::componentStyle
        FE_SC["Song Card (src/song-card)"]:::componentStyle
        FE_SS["Song Search (src/song-search)"]:::componentStyle
        FE_TM["Tournament Mode (src/tournament-mode)"]:::componentStyle
        FE_HZ["Hooks & Zustand (src/hooks & src/zustand)"]:::componentStyle
        AL["Assets & Localization (src/assets)"]:::assetsDir
    end

    %% Data Management & Import Pipelines
    subgraph "Data Management & Import Pipelines"
        DP["Data Import Scripts (scripts/)"]:::backendColor
    end

    %% Song Data Store
    DS["Song Data JSON (src/songs)"]:::dataStore

    %% Build & Deployment Infrastructure
    subgraph "Build & Deployment Infrastructure"
        BD["Build & Deployment Configs"]:::buildColor
    end

    %% Documentation & Community
    subgraph "Documentation & Community"
        DOC["Docs & Community (docs/)"]:::docsDir
    end

    %% External Data Sources
    External["External APIs/Web Pages"]:::external

    %% Relationships and Data Flow
    FE -->|"loads_data"| DS
    DP -->|"updates_data"| DS
    External -->|"feeds_data_to"| DP
    BD -->|"builds_deploys"| FE
    BD -->|"triggers_CI"| DOC

    %% Click Events for components
    click FE "https://github.com/noahm/ddrcarddraw/tree/main/src/"
    click FE_C "https://github.com/noahm/ddrcarddraw/tree/main/src/controls"
    click FE_SC "https://github.com/noahm/ddrcarddraw/tree/main/src/song-card"
    click FE_SS "https://github.com/noahm/ddrcarddraw/tree/main/src/song-search"
    click FE_TM "https://github.com/noahm/ddrcarddraw/tree/main/src/tournament-mode"
    click AL "https://github.com/noahm/ddrcarddraw/tree/main/src/assets"
    click DP "https://github.com/noahm/ddrcarddraw/tree/main/scripts/"
    click DS "https://github.com/noahm/ddrcarddraw/tree/main/src/songs"
    click BD "https://github.com/noahm/ddrcarddraw/blob/main/webpack.config.js"
    click DOC "https://github.com/noahm/ddrcarddraw/tree/main/docs/"

    %% Class Definitions for styling and colors
    classDef frontendColor fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef backendColor fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef buildColor fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef docsDir fill:#F5CBA7,stroke:#AF601A,stroke-width:2px;
    classDef assetsDir fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef dataStore fill:#FAD7A0,stroke:#F39C12,stroke-width:2px;
    classDef componentStyle fill:#D6EAF8,stroke:#5DADE2,stroke-width:1px;
    classDef external fill:#E6B0AA,stroke:#C0392B,stroke-width:1px;
```
