# vixan/ghost-in-the-graveyard architecture

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

- Interactive diagram: https://gitdiagram.com/vixan/ghost-in-the-graveyard
- Repository: https://github.com/vixan/ghost-in-the-graveyard

## Overview

##### Project type and purpose
- This is a single‐page, front‐end React/TypeScript simulation application.
- Purpose: visually simulate the “Ghost in the Graveyard” multi‐agent game using an HTML5 canvas (via Konva), with agents (Players, Ghosts, Exit, Tombstones) moving on a grid according to simple BDI‐inspired rules.

##### File structure
- Top level: package.json/lock, tsconfig.json, README, public/ (static HTML, manifest, robots.txt)
- src/
- App.tsx & index.tsx – application entry and root container
- components/
– ui/ (Button, NumberInput, RangeInput, Switch)
– Environment.tsx, Grid.tsx – canvas staging and layout
– agents/ (Agent base class, and specific Agent subcomponents: Ghost, Player, Exit, Tombstone)
- utils/ – pure helpers (gridUtils, positionUtils), custom hooks (useLatestState, useWindowSize)
- types/ – TS types (position, simulationStatus)
- reportWebVitals, react-app-env.d.ts – CRA boilerplate

##### README for additional insights
- Dependencies: React, TypeScript, react-konva/konva for canvas rendering, styled-components for styling, pathfinding for shortest‐path calculations.
- No backend or external services—pure client‐side logic.

##### Main components & their interactions
a. Presentation Layer (UI controls)
- Button, Inputs, Switch emit user events (start/stop, change grid size, speed).
- → Events dispatched to App’s state handler.
b. Simulation Engine
- Maintains current agent positions & statuses in React state.
- Uses gridUtils + positionUtils + pathfinding library to compute next moves.
- Custom hook (useLatestState) ensures engine always works on up‐to‐date state.
c. Rendering Layer
- Environment.tsx wraps a Konva Stage/Layer.
- Grid.tsx draws cell boundaries.
d. State Management
- Centralized in App.tsx via React hooks (useState, useEffect).
- Prop drilling or context passes state and updater functions to child components.
e. External libraries
- react-konva for canvas integration
- styled-components for styling UI controls
- pathfinding for graph search

##### Architectural patterns & design principles
- Component-based (separation of concerns between UI, simulation logic, rendering).
- Unidirectional data‐flow (Flux-like): UI → App state → Simulation engine → state updates → view re‐render.
- Custom hooks encapsulate cross‐cutting concerns (window resizing, latest state refs).
- Pure utility modules (gridUtils, positionUtils) isolated from React, making them testable.

##### Final advice
- Simulation loop explicitly, as that is the heart of the architecture.
- Use visual conventions consistently so that any new engineer can immediately see how state flows from user input through the engine to the canvas.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User"]:::external

    %% UI Controls Layer
    subgraph "UI Controls" 
        direction TB
        Button["Button"]:::ui
        NumberInput["NumberInput"]:::ui
        RangeInput["RangeInput"]:::ui
        Switch["Switch"]:::ui
    end

    %% Application Container
    subgraph "App Container & Entry" 
        direction TB
        App["App.tsx\n(App Container & State)"]:::app
        Index["index.tsx\n(Entry Point)"]:::app
    end

    %% Simulation Engine
    subgraph "Simulation Engine" 
        direction TB
        GridUtils["gridUtils.ts\n«Util»"]:::engine
        PositionUtils["positionUtils.ts\n«Util»"]:::engine
        Pathfinding["Pathfinding Lib\n«Lib»"]:::external
    end

    %% Rendering Layer
    subgraph "Rendering Layer" 
        direction TB
        Environment["Environment.tsx\n(Konva Stage & Layer)"]:::render
        GridComp["Grid.tsx\n(Cell Boundaries)"]:::render
        subgraph "Agents" 
            direction TB
            Agent["Agent.tsx\n(Base Class)"]:::render
            Ghost["Ghost.tsx"]:::render
            Player["Player.tsx"]:::render
            Exit["Exit.tsx"]:::render
            Tombstone["Tombstone.tsx"]:::render
        end
    end

    %% Custom Hooks
    subgraph "Custom Hooks" 
        direction TB
        LatestState["useLatestState.ts\n«Hook»"]:::hook
        WindowSize["useWindowSize.ts\n«Hook»"]:::hook
    end

    %% Type Definitions
    subgraph "Types" 
        direction TB
        PositionType["position.ts\n«Type»"]:::type
        StatusType["simulationStatus.ts\n«Type»"]:::type
    end

    %% CRA Boilerplate
    subgraph "CRA Boilerplate" 
        direction TB
        WebVitals["reportWebVitals.ts"]:::boiler
        EnvDecl["react-app-env.d.ts"]:::boiler
    end

    %% Runtime Environment
    Browser["Browser / Canvas Runtime"]:::external

    %% Timer for simulation loop
    Timer["requestAnimationFrame\n(Tick Loop)"]:::external

    %% Data Flow
    User --> Button
    User --> NumberInput
    User --> RangeInput
    User --> Switch
    Button --> App
    NumberInput --> App
    RangeInput --> App
    Switch --> App

    Index --> App

    App --> LatestState
    App --> WindowSize

    Timer --> App
    App --> GridUtils
    App --> PositionUtils
    App --> Pathfinding
    GridUtils --> Pathfinding
    PositionUtils --> Pathfinding

    App --> Environment
    Environment --> GridComp
    Environment --> Agent
    Agent --> Ghost
    Agent --> Player
    Agent --> Exit
    Agent --> Tombstone

    App --> Browser
    Environment --> Browser

    %% Styling
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef app fill:#343a40,stroke:#1d2124,color:#ffffff
    classDef engine fill:#d4edda,stroke:#155724,color:#155724
    classDef render fill:#ffe5b4,stroke:#e09b00,color:#8a4b00
    classDef hook fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#383d41
    classDef type fill:#f0f0f0,stroke:#999999,color:#333333
    classDef boiler fill:#f8f9fa,stroke:#ced4da,color:#495057

    %% Click Events
    click Button "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/components/ui/Button.tsx"
    click NumberInput "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/components/ui/NumberInput.tsx"
    click RangeInput "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/components/ui/RangeInput.tsx"
    click Switch "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/components/ui/Switch.tsx"
    click App "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/App.tsx"
    click Index "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/index.tsx"
    click GridUtils "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/utils/gridUtils.ts"
    click PositionUtils "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/utils/positionUtils.ts"
    click Environment "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/components/Environment.tsx"
    click GridComp "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/components/Grid.tsx"
    click Agent "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/components/agents/Agent.tsx"
    click Ghost "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/components/agents/Ghost.tsx"
    click Player "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/components/agents/Player.tsx"
    click Exit "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/components/agents/Exit.tsx"
    click Tombstone "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/components/agents/Tombstone.tsx"
    click LatestState "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/utils/useLatestState.ts"
    click WindowSize "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/utils/useWindowSize.ts"
    click PositionType "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/types/position.ts"
    click StatusType "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/types/simulationStatus.ts"
    click WebVitals "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/reportWebVitals.ts"
    click EnvDecl "https://github.com/vixan/ghost-in-the-graveyard/blob/main/src/react-app-env.d.ts"
```
