# lukehollanddev/algorithm-animator architecture

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

- Interactive diagram: https://gitdiagram.com/lukehollanddev/algorithm-animator
- Repository: https://github.com/lukehollanddev/algorithm-animator

## Overview

##### Project Type and Purpose
- This is a client-only Single Page Application (SPA) built with React.js, intended to aid learning by animating and visualizing graph-based (and eventually other) algorithms in the browser.
- There is no backend service—everything runs client-side—and it is hosted as a static site on GitHub Pages, with CI/CD pipelines in GitHub Actions.

##### File-Structure Analysis
- Top-level:
- public/  (static HTML/CSS/manifest for browser entry point)
- src/   (React source code)
- .github/workflows/ (CI/CD pipeline definitions)
- src/ subdirectories:
- algorithms/ (algorithm implementations: bfs.js, dijkstra.js)
- util/   (helpers, e.g. createStep)
- constant/ (configuration)
- assets/  (static images/fonts if any)
- __tests__ under components—unit tests run via Jest.

##### Architecture Overview from the README
- React.js for UI
- Node.js & Yarn for local dev/build
- ESLint & Jest for quality and testing
- GitHub Actions for build/test/deploy (three workflows: all.yml, develop.yml, prod.yml)
- GitHub Pages for static hosting (prod and dev URLs)

##### Main Components
A. Developer & CI/CD Pipeline
1. Developer Machine
- Node.js + Yarn + local Git repo
- IDE / code edits → src/ + public/
2. GitHub Repository
- .github/workflows/all.yml (runs lint + test)
- .github/workflows/develop.yml (build + deploy to dev URL)
- .github/workflows/prod.yml (build + deploy to prod URL)
3. GitHub Pages
- Hosts static bundle at https://amazonpriime.github.io/indproj (prod)
- Secondary for dev

B. Client (Browser)
1. Entry Point
- public/index.html → loads bundled JS/CSS
2. React Application
- App.js (root component)
- State Management (useState/useReducer hooks hold graph state, steps, playback index, speed)
3. UI Layer (components/)
- GraphBuilder ← user adds/edits nodes & edges
- AlgorithmSelector ← choose BFS, Dijkstra
- Graph ← visual node/edge rendering
- Playback ← controls (play/pause/step/speed)
- CodeViewer ← show pseudocode & highlight current step
- AlgInfo ← show description & complexity
4. Algorithm Engine (algorithms/)
- bfs.js, dijkstra.js export a function( graph, source, dest, directed ) → steps[]
- Steps created by util/createStep (in util/util.js)
5. Configuration & Constants
6. Assets & Styling
- CSS modules alongside each component
- index.css & App.css

- Developer → (push code) → GitHub Actions → (build/test) → GitHub Pages
- Browser → (HTTP GET) → GitHub Pages → returns index.html + bundle
- User interacts in Browser:
- GraphBuilder → updates App state → passes graph data to Algorithm Engine → returns steps[] → stored in App state
- Playback controls iterate through steps[] → trigger re-render of Graph + CodeViewer → animate changes
- Component Hierarchy: App.js at top → passes props & callbacks down to child components → child events bubble up

##### Architectural Patterns & Principles
- SPA (Single‐Page Application) hosted statically
- Component‐Based UI (React) with unidirectional data flow
- Separation of Concerns: UI vs. algorithm logic vs. utility vs. config
- CI/CD as code (GitHub Actions workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Deploy Layer
    subgraph "Build & Deploy"
        direction TB
        DeveloperMachine["Developer Machine"]:::buildDeploy
        GitHubRepo["GitHub Repository"]:::buildDeploy
        CI_All["all.yml"]:::buildDeploy
        CI_Develop["develop.yml"]:::buildDeploy
        CI_Prod["prod.yml"]:::buildDeploy
        GitHubPages[(“GitHub Pages”)]:::buildDeploy
    end

    %% Client-Side Application Layer
    subgraph "Client‐Side Application"
        direction TB
        Browser["Browser"]:::client

        subgraph "Entry Point"
            direction TB
            IndexHTML["index.html"]:::client
            Manifest["manifest.json"]:::client
            Robots["robots.txt"]:::client
        end

        subgraph "React Application"
            direction TB
            EntryJS["index.js"]:::client
            AppJS["App.js"]:::client
            AppCSS["App.css"]:::client
            IndexCSS["index.css"]:::client
        end

        subgraph "Modules"
            direction TB

            subgraph "UI Components"
                direction TB
                GraphBuilder["GraphBuilder"]:::client
                AlgorithmSelector["AlgorithmSelector"]:::client
                GraphComp["Graph"]:::client
                Playback["Playback"]:::client
                CodeViewer["CodeViewer"]:::client
                AlgInfo["AlgInfo"]:::client
                Legend["Legend"]:::client
                Header["Header"]:::client
                Footer["Footer"]:::client
                About["About"]:::client
                Contact["Contact"]:::client
                Guide["Guide"]:::client
                CreateTools["CreateTools"]:::client
            end

            subgraph "Algorithm Engine"
                direction TB
                BFS["bfs.js"]:::client
                Dijkstra["dijkstra.js"]:::client
                EngineIndex["index.js"]:::client
            end

            subgraph "Utility Functions"
                direction TB
                Util["util.js"]:::client
            end

            subgraph "Configuration & Constants"
                direction TB
                Config["config.js"]:::client
            end

            subgraph "Assets & Styling"
                direction TB
                Assets["assets/"]:::client
            end
        end
    end

    %% Connections: Build & Deploy
    DeveloperMachine -->|"push code"| GitHubRepo
    GitHubRepo -->|runs CI| CI_All
    GitHubRepo -->|runs CI| CI_Develop
    GitHubRepo -->|runs CI| CI_Prod
    CI_All -->|deploy| GitHubPages
    CI_Develop -->|deploy| GitHubPages
    CI_Prod -->|deploy| GitHubPages

    %% Connections: Browser to Hosting
    Browser -->|"HTTP GET /bundle"| GitHubPages
    GitHubPages -->|"returns index.html + bundle"| Browser

    %% Connections: Entry Point to React App
    Browser --> IndexHTML
    IndexHTML --> EntryJS
    EntryJS --> AppJS

    %% React App to Modules
    AppJS --> GraphBuilder
    AppJS --> AlgorithmSelector
    AppJS --> GraphComp
    AppJS --> Playback
    AppJS --> CodeViewer
    AppJS --> AlgInfo
    AppJS --> Legend
    AppJS --> Header
    AppJS --> Footer
    AppJS --> About
    AppJS --> Contact
    AppJS --> Guide
    AppJS --> CreateTools
    AppJS --> BFS
    AppJS --> Dijkstra
    AppJS --> EngineIndex
    AppJS --> Util
    AppJS --> Config
    AppJS --> Assets

    %% Data Flow in Client
    GraphBuilder -->|"update graph state"| AppJS
    AppJS -->|"invoke bfs/dijkstra()"| EngineIndex
    EngineIndex --> BFS
    EngineIndex --> Dijkstra
    BFS --> Util
    Dijkstra --> Util
    EngineIndex -->|"returns steps[]"| AppJS
    Playback -->|"controls steps[]"| AppJS
    AppJS --> GraphComp
    AppJS --> CodeViewer

    %% Click Events
    click CI_All "https://github.com/lukehollanddev/algorithm-animator/blob/main/.github/workflows/all.yml"
    click CI_Develop "https://github.com/lukehollanddev/algorithm-animator/blob/main/.github/workflows/develop.yml"
    click CI_Prod "https://github.com/lukehollanddev/algorithm-animator/blob/main/.github/workflows/prod.yml"
    click IndexHTML "https://github.com/lukehollanddev/algorithm-animator/blob/main/public/index.html"
    click Manifest "https://github.com/lukehollanddev/algorithm-animator/blob/main/public/manifest.json"
    click Robots "https://github.com/lukehollanddev/algorithm-animator/blob/main/public/robots.txt"
    click EntryJS "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/index.js"
    click AppJS "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/App.js"
    click AppCSS "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/App.css"
    click IndexCSS "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/index.css"
    click GraphBuilder "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/components/GraphBuilder.js"
    click AlgorithmSelector "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/components/AlgorithmSelector.js"
    click GraphComp "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/components/Graph.js"
    click Playback "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/components/Playback.js"
    click CodeViewer "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/components/CodeViewer.js"
    click AlgInfo "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/components/AlgInfo.js"
    click Legend "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/components/Legend.js"
    click Header "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/components/Header.js"
    click Footer "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/components/Footer.js"
    click About "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/components/About.js"
    click Contact "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/components/Contact.js"
    click Guide "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/components/Guide.js"
    click CreateTools "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/components/CreateTools.js"
    click BFS "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/algorithms/bfs.js"
    click Dijkstra "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/algorithms/dijkstra.js"
    click EngineIndex "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/algorithms/index.js"
    click Util "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/util/util.js"
    click Config "https://github.com/lukehollanddev/algorithm-animator/blob/main/src/constant/config.js"
    click Assets "https://github.com/lukehollanddev/algorithm-animator/tree/main/src/assets/"

    %% Styles
    classDef buildDeploy fill:#fde2e2,stroke:#d79922,stroke-width:2px
    classDef client fill:#e2f0fd,stroke:#2266d7,stroke-width:2px
```
