# sotsf/conjurer architecture

> Architecture diagram of the GitHub repository sotsf/conjurer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sotsf/conjurer
- Repository: https://github.com/sotsf/conjurer

## Overview

The system architecture should be represented in multiple layers, focusing on these key components:

##### Frontend Architecture (Client-Side)
- Pages (/, /viewer, /portal, /playground, /beatMapper)
- Components hierarchy (showing major components like Canvas, Timeline, PatternPlayground)
- State Management (MobX stores: AudioStore, BeatMapStore, ExperienceStore, etc.)
- Rendering pipeline:
- ThreeJS/React Three Fiber integration
- Pattern/Effect shader system
- WebGL rendering flow

##### Backend Architecture
- API Layer:
- tRPC routers (experience, beatMap, playlist, song, user)
- API endpoints for file uploads
- Database Layer:
- Turso/SQLite (show both production and local configurations)
- Drizzle ORM integration

##### Real-time Communication
- WebSocket layer showing:
- Connection to Unity bridge
- Voice command handling
- Frame data transmission

Use these visual elements:
- Blue: Frontend components
- Green: Backend services
- Purple: Database
- Orange: WebSocket/real-time features
- Yellow: External services (Unity, LED Canopy)

**[Client Browser]**

- React Frontend
- Pages Layer
- Component Layer
- State Management (MobX)
- Rendering Pipeline (ThreeJS)

- WebSocket Client
- Frame Data Transmission

**[Server]**
- Next.js API Routes
- tRPC Routers
- WebSocket Server
- Database Layer (Turso/SQLite)

**[External Systems]**
- Unity Bridge
- LED Canopy

Important architectural patterns to highlight:
##### Real-time data flow for LED control

Special considerations:
- Data flow for audio-visual synchronization
- Pattern/effect pipeline
- Demonstrate how parameter variations affect the rendering
- Database schema relationships
- Deployment architecture (Vercel hosting)

Remember to:
##### Both development and production configurations

This architecture should emphasize the real-time nature of the application and its ability to handle complex audio-visual processing while maintaining performance.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client["Client Browser"]
        FE["React Frontend"]
        
        subgraph Pages["Pages Layer"]
            Index["Home Page"]:::frontend
            Viewer["Viewer"]:::frontend
            Portal["Portal"]:::frontend
            Playground["Playground"]:::frontend
            BeatMapper["Beat Mapper"]:::frontend
        end

        subgraph Components["Component Layer"]
            RP["Render Pipeline"]:::frontend
            Canvas["Display Canvas"]:::frontend
            Preview["Preview Canvas"]:::frontend
            Timeline["Timeline"]:::frontend
            AudioControls["Audio Controls"]:::frontend
            ExpEditor["Experience Editor"]:::frontend
        end

        subgraph State["State Management (MobX)"]
            AudioStore["Audio Store"]:::store
            BeatStore["Beat Map Store"]:::store
            ExpStore["Experience Store"]:::store
            PlayStore["Playground Store"]:::store
            PlaylistStore["Playlist Store"]:::store
            UIStore["UI Store"]:::store
        end

        subgraph Render["Rendering Pipeline"]
            ThreeJS["Three.js/R3F"]:::render
            Patterns["Pattern System"]:::render
            Effects["Effects System"]:::render
            ParamVar["Parameter Variations"]:::render
        end

        WSClient["WebSocket Client"]:::websocket
    end

    subgraph Server["Server Layer"]
        NextAPI["Next.js API Routes"]:::api
        
        subgraph TRPC["tRPC Routers"]
            ExpRouter["Experience Router"]:::api
            BeatRouter["Beat Map Router"]:::api
            PlayRouter["Playlist Router"]:::api
            SongRouter["Song Router"]:::api
            UserRouter["User Router"]:::api
        end

        WSServer["WebSocket Server"]:::websocket
        Upload["File Upload API"]:::api

        subgraph DB["Database Layer"]
            Turso["Turso/SQLite"]:::db
            Schema["Database Schema"]:::db
            Local["Local DB"]:::db
            Prod["Production DB"]:::db
        end
    end

    subgraph External["External Systems"]
        Unity["Unity Bridge"]:::external
        LED["LED Canopy"]:::external
    end

    %% Connections
    FE --> WSClient
    WSClient <--> WSServer
    WSServer <--> Unity
    Unity --> LED
    FE --> NextAPI
    NextAPI --> TRPC
    TRPC --> DB

    %% Click Events
    click Index "https://github.com/sotsf/conjurer/blob/main/src/pages/index.tsx"
    click Viewer "https://github.com/sotsf/conjurer/blob/main/src/pages/viewer.tsx"
    click Portal "https://github.com/sotsf/conjurer/blob/main/src/pages/portal.tsx"
    click Playground "https://github.com/sotsf/conjurer/blob/main/src/pages/playground.tsx"
    click BeatMapper "https://github.com/sotsf/conjurer/blob/main/src/pages/beatMapper.tsx"
    
    click AudioStore "https://github.com/sotsf/conjurer/blob/main/src/types/AudioStore.ts"
    click BeatStore "https://github.com/sotsf/conjurer/blob/main/src/types/BeatMapStore.ts"
    click ExpStore "https://github.com/sotsf/conjurer/blob/main/src/types/ExperienceStore.ts"
    click PlayStore "https://github.com/sotsf/conjurer/blob/main/src/types/PlaygroundStore.ts"
    click PlaylistStore "https://github.com/sotsf/conjurer/blob/main/src/types/PlaylistStore.ts"
    click UIStore "https://github.com/sotsf/conjurer/blob/main/src/types/UIStore.ts"
    
    click RP "https://github.com/sotsf/conjurer/blob/main/src/components/RenderPipeline/RenderPipeline.tsx"
    click Canvas "https://github.com/sotsf/conjurer/blob/main/src/components/Canvas/DisplayCanvas.tsx"
    click Preview "https://github.com/sotsf/conjurer/blob/main/src/components/Canvas/PreviewCanvas.tsx"
    
    click ExpRouter "https://github.com/sotsf/conjurer/blob/main/src/server/routers/experienceRouter.ts"
    click BeatRouter "https://github.com/sotsf/conjurer/blob/main/src/server/routers/beatMapRouter.ts"
    click PlayRouter "https://github.com/sotsf/conjurer/blob/main/src/server/routers/playlistRouter.ts"
    click SongRouter "https://github.com/sotsf/conjurer/blob/main/src/server/routers/songRouter.ts"
    click UserRouter "https://github.com/sotsf/conjurer/blob/main/src/server/routers/userRouter.ts"
    
    click Schema "https://github.com/sotsf/conjurer/blob/main/src/db/schema.ts"
    click Local "https://github.com/sotsf/conjurer/blob/main/src/db/local.ts"
    click Prod "https://github.com/sotsf/conjurer/blob/main/src/db/prod.ts"
    
    click WSServer "https://github.com/sotsf/conjurer/blob/main/src/websocket/websocketHost.ts"
    click Patterns "https://github.com/sotsf/conjurer/tree/main/src/patterns"
    click Effects "https://github.com/sotsf/conjurer/tree/main/src/effects"
    click Timeline "https://github.com/sotsf/conjurer/blob/main/src/components/Timeline/Timeline.tsx"
    click AudioControls "https://github.com/sotsf/conjurer/blob/main/src/components/AudioControls.tsx"
    click ParamVar "https://github.com/sotsf/conjurer/tree/main/src/components/ParameterVariations"
    click Upload "https://github.com/sotsf/conjurer/blob/main/src/app/api/upload/route.ts"
    click ExpEditor "https://github.com/sotsf/conjurer/blob/main/src/components/ExperienceEditor/ExperienceEditorPage.tsx"

    %% Styles
    classDef frontend fill:#3498db,color:white
    classDef api fill:#2ecc71,color:white
    classDef db fill:#9b59b6,color:white
    classDef websocket fill:#e67e22,color:white
    classDef external fill:#f1c40f,color:white
    classDef store fill:#1abc9c,color:white
    classDef render fill:#34495e,color:white
```
