# alae-touba/pathfinding-visualisation architecture

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

- Interactive diagram: https://gitdiagram.com/alae-touba/pathfinding-visualisation
- Repository: https://github.com/alae-touba/pathfinding-visualisation

## Overview

##### Project Type and Purpose
- This is a single‐page, static front-end application built with TypeScript, HTML, and CSS.

##### File Structure
- Top-level:
- src/ — TypeScript source code, divided into algorithms.ts (core algorithms), main.ts (app bootstrap + UI interaction), utils.ts (helper functions).
- build/ — transpiled JavaScript artifacts (algorithms.js, main.js, utils.js).
- static/ — CSS (styles.css), images (app demo), and a video demo.
- index.html — entry point, references build/*.js and static/styles.css.
- tsconfig.json, package.json — build and dependency configs.

##### Extract Key Architectural Insights from README
- Build pipeline: npm run build ⇒ tsc compiles src → build.
- No backend or external API—everything runs in‐browser.
- Interactivity via DOM events and a grid data structure in memory.

##### Main Components & Their Relationships
a. Components:
1. Developer Environment & Build Pipeline
- TypeScript Compiler (tsc)
- npm scripts (build, watch)
2. Static Server / Hosting
- index.html + static/ assets served (GitHub Pages)
3. Front-end Modules (loaded in browser)
- Grid Data Model (utils.js): maintains grid cells, start/end coordinates, blocked cells.
- Algorithm Engine (algorithms.js): implements DFS, BFS, Bellman-Ford, Dijkstra logic on the grid model.
4. Static Assets
- CSS for styling (static/styles.css)
- Images & video for documentation (static/images, static/pathfinding-visualisation.mp4)

b. Interactions & Data Flow:
- Developer writes TS in src/
→ (tsc)
→ build/JS
→ index.html loads JS & CSS
→ Browser
- In browser:
- UI Controller captures user events → updates Grid Model
- Renderer takes results → updates the DOM grid
- Static assets (styles.css) affect presentation; images used only in docs, not in runtime.

c. Architectural Patterns & Principles:
- Modular separation:
- Algorithm logic is decoupled from DOM (pure functions in algorithms.js).
- Grid state and utility functions live in a separate module (utils.js).
- UI orchestration and DOM manipulation centralized in main.js.
- Build pipeline separates source from distribution.
- Clear layering: Build tools → Static hosting → Browser execution → User interactions.

d. Technologies & Frameworks:
- TypeScript (tsc)
- Plain HTML/CSS/Vanilla JS (no framework)
- npm for scripts & dependency management
- GitHub Pages (static hosting)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Build Pipeline
    subgraph "Build Pipeline"
        direction TB
        pkg["package.json"]:::build
        tsconfig["tsconfig.json"]:::build
        tsc["TypeScript Compiler (tsc)"]:::build
        npm["npm scripts (build, watch)"]:::build
        pkg --> npm
        tsconfig --> tsc
        npm --> tsc
        tsc --> buildDir
    end

    buildDir["build/ (build artifacts)"]:::build
    subgraph "Build Artifacts"
        direction TB
        algorithmsJS["algorithms.js"]:::algo
        mainJS["main.js"]:::core
        utilsJS["utils.js"]:::core
        buildDir --> algorithmsJS
        buildDir --> mainJS
        buildDir --> utilsJS
    end

    %% Static Hosting
    subgraph "Static Hosting"
        direction TB
        index["index.html"]:::core
        staticDir["static/ (assets)"]:::static
        index --> staticDir
    end

    %% Load phase
    index --> mainJS
    index --> algorithmsJS
    index --> utilsJS
    index -->|"loads CSS"| stylesCSS

    staticDir --> stylesCSS["styles.css"]:::static
    staticDir --> images["images/"]:::static
    staticDir --> video["pathfinding-visualisation.mp4"]:::static

    %% Runtime in Browser
    subgraph "Browser Runtime" 
        direction TB
        UI["UI Controller"]:::core
        Grid["Grid Data Model"]:::core
        Algo["Algorithm Engine"]:::algo
        Render["Renderer"]:::core
        DOM["Browser DOM"]:::core

        UI --> Grid
        Grid --> Algo
        Algo --> Render
        Render --> DOM
        DOM --> UI
    end

    %% Interactions
    User["User Events"]:::ext --> UI

    %% Legend
    subgraph "Legend"
        direction TB
        LB["Build/Deployment"]:::build
        LC["Core Front-end"]:::core
        LA["Algorithm Logic"]:::algo
        LS["Static Assets"]:::static
    end

    %% Click Events
    click pkg "https://github.com/alae-touba/pathfinding-visualisation/blob/master/package.json"
    click tsconfig "https://github.com/alae-touba/pathfinding-visualisation/blob/master/tsconfig.json"
    click buildDir "https://github.com/alae-touba/pathfinding-visualisation/tree/master/build/"
    click index "https://github.com/alae-touba/pathfinding-visualisation/blob/master/index.html"
    click staticDir "https://github.com/alae-touba/pathfinding-visualisation/tree/master/static/"
    click mainJS "https://github.com/alae-touba/pathfinding-visualisation/blob/master/build/main.js"
    click algorithmsJS "https://github.com/alae-touba/pathfinding-visualisation/blob/master/build/algorithms.js"
    click utilsJS "https://github.com/alae-touba/pathfinding-visualisation/blob/master/build/utils.js"
    click UI "https://github.com/alae-touba/pathfinding-visualisation/blob/master/src/main.ts"
    click Grid "https://github.com/alae-touba/pathfinding-visualisation/blob/master/src/utils.ts"
    click Algo "https://github.com/alae-touba/pathfinding-visualisation/blob/master/src/algorithms.ts"

    %% Styles
    classDef build fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef core fill:#90EE90,stroke:#000,stroke-width:1px
    classDef algo fill:#FFA500,stroke:#000,stroke-width:1px
    classDef static fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef ext fill:#FFFFFF,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
