# haigpapa/photon architecture

> Architecture diagram of the GitHub repository haigpapa/photon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/haigpapa/photon
- Repository: https://github.com/haigpapa/photon

## Overview

##### Project type and purpose
- photon+ is a client-side, full-feature physics-based generative music tool built with React and TypeScript.
- It simulates optical ray tracing on a 2D grid and translates beam–sensor collisions into Web Audio API events, rendering both canvas visuals and real-time audio.

##### File structure
- Top-level entrypoints:
- index.html, index.tsx → bootstraps the React app via Vite (vite.config.ts)
- App.tsx → root component, glues together UI, state, and simulation
- components/ → reusable UI (ControlPanel, GridCanvas, PresetModal, ErrorBoundary, Grid)
- services/ → domain logic and side-effects:
- simulation.ts (physics tick, ray tracing, collision detection)
- audioService.ts (Web Audio API wrappers)
- storageService.ts (localStorage/preset save-load)
- shareService.ts (export/share presets)
- geminiService.ts (optional AI integration)
- utils/ → stateless helpers (validation, geometry math)
- tests/ (__tests__, vitest.config.ts) → unit tests for simulation, share, storage, validation
- config/build files (.env.example, tsconfig.json, vite.config.ts, prettier, eslint, husky)

##### README for additional insights
- Core architecture described under “Architectural Approach” and illustrated in ARCHITECTURE.md.
- System boundary: inputs (user grid layout & beam params), transformation (physics engine), outputs (audio synthesis, visuals, MIDI export).
- Key abstractions: optical ray tracing, event-driven audio, grid as state machine; trade-offs (CPU, determinism) and patterns (recursive propagation).

##### Detail over minimalism
- Recursive loops in the physics engine to show maxBounce termination

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Root & Bootstrapping"
        direction TB
        HTML["index.html"]:::config
        Entry["index.tsx"]:::frontend
        App["App.tsx"]:::frontend
        Vite["vite.config.ts"]:::config
    end

    subgraph "User Interface Layer"
        direction TB
        CP["ControlPanel"]:::frontend
        GC["GridCanvas"]:::frontend
        PM["PresetModal"]:::frontend
        G["Grid"]:::frontend
        EB["ErrorBoundary"]:::frontend
    end

    subgraph "State Management"
        direction TB
        State["Zustand/React Context"]:::service
    end

    subgraph "Core Engine Layer"
        direction TB
        Physics["simulation.ts"]:::core
    end

    subgraph "Audio Layer"
        direction TB
        Audio["audioService.ts"]:::core
    end

    subgraph "Visual Rendering Layer"
        direction TB
        Visual["Canvas2D/Three.js\n(GridCanvas)"]:::external
    end

    subgraph "Persistence & Sharing"
        direction TB
        Storage["storageService.ts"]:::persistence
        Share["shareService.ts"]:::persistence
        Gemini["geminiService.ts"]:::persistence
    end

    subgraph "Utils"
        direction TB
        Validation["validation.ts"]:::utility
    end

    subgraph "Configuration & Tests"
        direction TB
        Arch["ARCHITECTURE.md"]:::config
        Readme["README.md"]:::config
        TSconfig["tsconfig.json"]:::config
        Env[".env.example"]:::config
        Package["package.json"]:::config
        simTest["simulation.test.ts"]:::test
        shareTest["shareService.test.ts"]:::test
        storageTest["storageService.test.ts"]:::test
        validTest["validation.test.ts"]:::test
    end

    HTML --> Entry
    Entry --> App
    App --> CP
    App --> GC
    App --> PM
    App --> G
    App --> EB

    CP --> State
    GC --> State
    PM --> State
    G --> State
    EB --> State

    State --> Physics
    Physics --> Audio
    Physics --> Visual

    CP --> Storage
    CP --> Share
    CP --> Gemini

    Validation --> Physics
    Validation --> Share
    Validation --> Storage

    classDef frontend fill:#add8e6,stroke:#333,stroke-width:1px
    classDef core fill:#90ee90,stroke:#333,stroke-width:1px
    classDef external fill:#ffa500,stroke:#333,stroke-width:1px
    classDef persistence fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef service fill:#d0f0c0,stroke:#333,stroke-width:1px
    classDef utility fill:#f0e68c,stroke:#333,stroke-width:1px
    classDef config fill:#f5f5f5,stroke:#333,stroke-width:1px
    classDef test fill:#ffe4e1,stroke:#333,stroke-width:1px

    click CP "https://github.com/haigpapa/photon/blob/main/components/ControlPanel.tsx"
    click GC "https://github.com/haigpapa/photon/blob/main/components/GridCanvas.tsx"
    click PM "https://github.com/haigpapa/photon/blob/main/components/PresetModal.tsx"
    click G "https://github.com/haigpapa/photon/blob/main/components/Grid.tsx"
    click EB "https://github.com/haigpapa/photon/blob/main/components/ErrorBoundary.tsx"
    click HTML "https://github.com/haigpapa/photon/blob/main/index.html"
    click Entry "https://github.com/haigpapa/photon/blob/main/index.tsx"
    click App "https://github.com/haigpapa/photon/blob/main/App.tsx"
    click Vite "https://github.com/haigpapa/photon/blob/main/vite.config.ts"
    click Physics "https://github.com/haigpapa/photon/blob/main/services/simulation.ts"
    click Audio "https://github.com/haigpapa/photon/blob/main/services/audioService.ts"
    click Storage "https://github.com/haigpapa/photon/blob/main/services/storageService.ts"
    click Share "https://github.com/haigpapa/photon/blob/main/services/shareService.ts"
    click Gemini "https://github.com/haigpapa/photon/blob/main/services/geminiService.ts"
    click Validation "https://github.com/haigpapa/photon/blob/main/utils/validation.ts"
    click simTest "https://github.com/haigpapa/photon/blob/main/services/__tests__/simulation.test.ts"
    click shareTest "https://github.com/haigpapa/photon/blob/main/services/__tests__/shareService.test.ts"
    click storageTest "https://github.com/haigpapa/photon/blob/main/services/__tests__/storageService.test.ts"
    click validTest "https://github.com/haigpapa/photon/blob/main/utils/__tests__/validation.test.ts"
    click Arch "https://github.com/haigpapa/photon/blob/main/ARCHITECTURE.md"
    click Readme "https://github.com/haigpapa/photon/blob/main/README.md"
    click TSconfig "https://github.com/haigpapa/photon/blob/main/tsconfig.json"
    click Env "https://github.com/haigpapa/photon/blob/main/.env.example"
    click Package "https://github.com/haigpapa/photon/blob/main/package.json"
```
