# madavidcoder/circle-seige architecture

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

- Interactive diagram: https://gitdiagram.com/madavidcoder/circle-seige
- Repository: https://github.com/madavidcoder/circle-seige

## Overview

1. **Overall shape**
   Circle Siege is a two-part game: a **Godot frontend** for rendering, input, UI, and gameplay, and a **Rust backend** for audio analysis. The architectural boundary is between the real-time game client and the audio/event-generation layer.

2. **Frontend runtime**
   The `frontend/` directory is the main shipped game. It contains a Godot project (`project.godot`), scenes (`main.tscn`, `ChordTelegraph.tscn`, `Projectile.tscn`, `RadialTelegraph.tscn`), and many GDScript components that implement the menu, game loop, HUD, and effects.

3. **Frontend composition**
   The game client is organized as scene-based modules:
   - `main.gd` / `main.tscn` for top-level app flow
   - `menu.gd` for start/settings/input selection
   - `director.gd` for orchestrating gameplay events
   - `player.gd` for cursor-following player behavior
   - `projectile.gd`, `chord_telegraph.gd`, `radial_telegraph.gd` for hazards and warning visuals
   - `lives_display.gd`, `near_miss_fx.gd`, `shockwave.gd`, `beat_particles.gd`, `spectrum.gd` for feedback and HUD

4. **Gameplay data flow**
   The primary in-game flow is: **audio source selection → beat/energy analysis → spawning of telegraphs/projectiles → player dodges with mouse input → HUD/visual feedback updates**. The `director` appears to be the central gameplay coordinator that turns audio timing into attack patterns.

5. **Audio source modes**
   The README and assets show three input modes:
   - **Demo tracks** bundled as `demo_*.jsonl` and `demo.wav`
   - **Local file** input chosen by the player
   - **System audio loopback** for live music from apps like Spotify  
   This is a major architectural boundary because the backend must handle multiple audio sources, while the frontend presents them as game modes.

6. **Rust backend role**
   The `backend/` crate is a separate Rust executable with `main.rs`, `processor.rs`, and `record.rs`. Based on the README tech stack, it handles **audio analysis, FFT/tempo/beat detection, and record generation**. It is not the game itself; it is the analysis engine that produces timing/intensity data for the frontend to consume.

7. **Backend responsibilities**
   The backend likely has three concerns:
   - command-line startup and configuration (`clap` in the README)
   - asynchronous processing / streaming (`tokio`)
   - beat and tempo analysis (`aubio`, plus any FFT/feature extraction logic in `processor.rs`)  
   `record.rs` likely defines the event/trace format used for playback or exporting analysis results.

8. **Trace-based playback**
   The presence of `demo_chill.jsonl`, `demo_normal.jsonl`, and `demo_hard.jsonl` suggests the game can play back **precomputed event traces** rather than analyzing audio every time. That makes the frontend capable of deterministic demo playback, while the backend likely generates or records these traces for live or offline use.

9. **Visual and accessibility layer**
   The frontend includes custom shaders and theme resources (`flow_gradient.gdshader`, `*.tres`, `gradient_bg.gd`, `audiowide.tres`, `syne*.tres`) plus settings for movement reduction and high-contrast modes. This is a distinct UI/visual subsystem layered on top of gameplay, not part of the audio analysis pipeline.

10. **Input and control model**
   Player control is intentionally minimal: the mouse position drives the player avatar, and keyboard input is mostly reserved for menu navigation. That means the core runtime loop is: **cursor input + audio-derived hazards + collision/life management**.

11. **External dependency boundary**
   The project depends on **Godot Engine** for the client runtime and **Rust** for analysis tooling. The README also calls out a Windows-only limitation due to audio loopback compatibility, which affects deployment architecture because system-audio capture is part of the core feature set.

12. **How to draw the architecture**
   A useful diagram would show:
   - a **Godot game client** containing menu, gameplay director, entities, HUD, and effects
   - a **Rust audio analysis service/tool** producing beat/event records
   - **audio inputs** feeding the Rust side
   - **JSONL/demo traces or live analysis output** feeding the game director
   - **mouse/keyboard input** feeding the player/menu
   - **rendered visuals and collision feedback** as the client’s output  
   The central integration point is the event stream that converts music into obstacle patterns.

Main entry points: [`frontend/director.gd`](https://github.com/madavidcoder/circle-seige/blob/main/frontend/director.gd) (Director), [`frontend/main.gd`](https://github.com/madavidcoder/circle-seige/blob/main/frontend/main.gd) (Main app), [`frontend/arena.gd`](https://github.com/madavidcoder/circle-seige/blob/main/frontend/arena.gd) (Arena), [`frontend/menu.gd`](https://github.com/madavidcoder/circle-seige/blob/main/frontend/menu.gd) (Menu)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Godot Client"]
  node_main_app["Main app<br/>scene flow<br/>[main.gd]"]
  node_menu["Menu<br/>ui flow<br/>[menu.gd]"]
  node_director["Director<br/>gameplay core<br/>[director.gd]"]
  node_player(("Player<br/>avatar control<br/>[player.gd]"))
  node_arena["Arena<br/>playfield<br/>[arena.gd]"]
  node_projectile["Projectile<br/>hazard entity<br/>[projectile.gd]"]
  node_chord_telegraph["Chord tel.<br/>warning entity<br/>[chord_telegraph.gd]"]
  node_radial_telegraph["Radial tel.<br/>warning entity"]
  node_hud["HUD<br/>status ui<br/>[lives_display.gd]"]
  node_fx["Effects<br/>feedback fx<br/>[near_miss_fx.gd]"]
  node_camera(("Camera<br/>view control<br/>[camera_2d.gd]"))
  node_config["Config<br/>settings<br/>[config.gd]"]
end

subgraph group_backend["Rust Analysis"]
  node_backend_main["Backend CLI<br/>rust entrypoint<br/>[main.rs]"]
  node_processor["Processor<br/>audio analysis<br/>[processor.rs]"]
  node_record["Record format<br/>trace schema<br/>[record.rs]"]
end

subgraph group_assets["Assets & Traces"]
  node_audio_inputs[("Audio input<br/>source modes<br/>[demo.wav]")]
  node_demo_traces["Demo traces<br/>jsonl playback<br/>[demo_normal.jsonl]"]
  node_visual_assets["Visual assets<br/>themes shaders"]
end

node_main_app -->|"routes to"| node_menu
node_main_app -->|"loads gameplay"| node_director
node_main_app -->|"applies settings"| node_config
node_menu -->|"selects mode"| node_audio_inputs
node_menu -->|"launches analysis"| node_backend_main
node_director -->|"drives encounters"| node_player
node_director -->|"spawns"| node_projectile
node_director -->|"spawns"| node_chord_telegraph
node_director -->|"spawns"| node_radial_telegraph
node_director -->|"updates"| node_hud
node_director -->|"triggers"| node_fx
node_player -->|"moves in"| node_arena
node_projectile -->|"collides in"| node_arena
node_chord_telegraph -->|"warns in"| node_arena
node_radial_telegraph -->|"warns in"| node_arena
node_backend_main -->|"orchestrates"| node_processor
node_processor -->|"emits"| node_record
node_audio_inputs -->|"feeds"| node_processor
node_record -->|"serializes as"| node_demo_traces
node_demo_traces -->|"replays into"| node_director
node_visual_assets -->|"skins"| node_main_app
node_visual_assets -->|"supports"| node_fx

click node_main_app "https://github.com/madavidcoder/circle-seige/blob/main/frontend/main.gd"
click node_menu "https://github.com/madavidcoder/circle-seige/blob/main/frontend/menu.gd"
click node_director "https://github.com/madavidcoder/circle-seige/blob/main/frontend/director.gd"
click node_player "https://github.com/madavidcoder/circle-seige/blob/main/frontend/player.gd"
click node_arena "https://github.com/madavidcoder/circle-seige/blob/main/frontend/arena.gd"
click node_projectile "https://github.com/madavidcoder/circle-seige/blob/main/frontend/projectile.gd"
click node_chord_telegraph "https://github.com/madavidcoder/circle-seige/blob/main/frontend/chord_telegraph.gd"
click node_radial_telegraph "https://github.com/madavidcoder/circle-seige/blob/main/frontend/radial_telegraph.gd"
click node_hud "https://github.com/madavidcoder/circle-seige/blob/main/frontend/lives_display.gd"
click node_fx "https://github.com/madavidcoder/circle-seige/blob/main/frontend/near_miss_fx.gd"
click node_camera "https://github.com/madavidcoder/circle-seige/blob/main/frontend/camera_2d.gd"
click node_config "https://github.com/madavidcoder/circle-seige/blob/main/frontend/config.gd"
click node_backend_main "https://github.com/madavidcoder/circle-seige/blob/main/backend/src/main.rs"
click node_processor "https://github.com/madavidcoder/circle-seige/blob/main/backend/src/processor.rs"
click node_record "https://github.com/madavidcoder/circle-seige/blob/main/backend/src/record.rs"
click node_audio_inputs "https://github.com/madavidcoder/circle-seige/blob/main/frontend/demo.wav"
click node_demo_traces "https://github.com/madavidcoder/circle-seige/blob/main/frontend/demo_normal.jsonl"
click node_visual_assets "https://github.com/madavidcoder/circle-seige/blob/main/frontend/flow_gradient.gdshader"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_app,node_menu,node_director,node_player,node_arena,node_projectile,node_chord_telegraph,node_radial_telegraph,node_hud,node_fx,node_camera,node_config toneBlue
class node_backend_main,node_processor,node_record toneAmber
class node_audio_inputs,node_demo_traces,node_visual_assets toneMint
```

## Components

### Godot Client

Real-time game client built in Godot.

- [Main app](https://github.com/madavidcoder/circle-seige/blob/main/frontend/main.gd): scene flow · Top-level game state and scene entry point. · `frontend/main.gd`
- [Menu](https://github.com/madavidcoder/circle-seige/blob/main/frontend/menu.gd): ui flow · Start, settings, and input mode selection. · `frontend/menu.gd`
- [Director](https://github.com/madavidcoder/circle-seige/blob/main/frontend/director.gd): gameplay core · Converts timing data into attacks and gameplay events. · `frontend/director.gd`
- [Player](https://github.com/madavidcoder/circle-seige/blob/main/frontend/player.gd): avatar control · Mouse-driven player movement and dodge behavior. · `frontend/player.gd`
- [Arena](https://github.com/madavidcoder/circle-seige/blob/main/frontend/arena.gd): playfield · Core playfield and collision space. · `frontend/arena.gd`
- [Projectile](https://github.com/madavidcoder/circle-seige/blob/main/frontend/projectile.gd): hazard entity · Primary moving obstacle spawned during play. · `frontend/projectile.gd`
- [Chord tel.](https://github.com/madavidcoder/circle-seige/blob/main/frontend/chord_telegraph.gd): warning entity · Telegraphed hazard indicating upcoming patterns. · `frontend/chord_telegraph.gd`
- [Radial tel.](https://github.com/madavidcoder/circle-seige/blob/main/frontend/radial_telegraph.gd): warning entity · Area-style warning visualization for attacks. · `frontend/radial_telegraph.gd`
- [HUD](https://github.com/madavidcoder/circle-seige/blob/main/frontend/lives_display.gd): status ui · Lives and spectrum feedback shown during play. · `frontend/lives_display.gd`
- [Effects](https://github.com/madavidcoder/circle-seige/blob/main/frontend/near_miss_fx.gd): feedback fx · Near-miss, shockwave, and beat-reactive visuals. · `frontend/near_miss_fx.gd`
- [Camera](https://github.com/madavidcoder/circle-seige/blob/main/frontend/camera_2d.gd): view control · Scene camera behavior for gameplay framing. · `frontend/camera_2d.gd`
- [Config](https://github.com/madavidcoder/circle-seige/blob/main/frontend/config.gd): settings · Runtime configuration and accessibility options. · `frontend/config.gd`

### Rust Analysis

Audio analysis and trace generation tooling.

- [Backend CLI](https://github.com/madavidcoder/circle-seige/blob/main/backend/src/main.rs): rust entrypoint · Command-line startup and orchestration for analysis. · `backend/src/main.rs`
- [Processor](https://github.com/madavidcoder/circle-seige/blob/main/backend/src/processor.rs): audio analysis · Streaming audio processing, FFT, tempo, and beat detection. · `backend/src/processor.rs`
- [Record format](https://github.com/madavidcoder/circle-seige/blob/main/backend/src/record.rs): trace schema · Event/trace representation for demo playback or export. · `backend/src/record.rs`

### Assets & Traces

Bundled audio, traces, and visual resources.

- [Audio input](https://github.com/madavidcoder/circle-seige/blob/main/frontend/demo.wav): source modes · Demo tracks, local files, and system loopback audio. · `frontend/demo.wav`
- [Demo traces](https://github.com/madavidcoder/circle-seige/blob/main/frontend/demo_normal.jsonl): jsonl playback · Precomputed challenge traces for deterministic playback. · `frontend/demo_normal.jsonl`
- [Visual assets](https://github.com/madavidcoder/circle-seige/blob/main/frontend/flow_gradient.gdshader): themes shaders · Fonts, shaders, and theme resources for presentation. · `frontend/flow_gradient.gdshader`

## Connections

- Main app → Menu: routes to · Starts in menus and setup flows.
- Main app → Director: loads gameplay · Enters the active game loop.
- Main app → Config: applies settings · Reads runtime and accessibility options.
- Menu → Audio input: selects mode · Chooses demo, local file, or system audio.
- Menu → Backend CLI: launches analysis · Starts analysis path for live or local audio.
- Director → Player: drives encounters · Coordinates hazards against player movement.
- Director → Projectile: spawns · Creates moving hazards from beat events.
- Director → Chord tel.: spawns · Creates advance warnings for patterns.
- Director → Radial tel.: spawns · Creates area warning visuals.
- Director → HUD: updates · Feeds lives, timing, and spectrum state.
- Director → Effects: triggers · Emits hit and beat feedback effects.
- Player → Arena: moves in · Player stays constrained to the playfield.
- Projectile → Arena: collides in · Hazards interact with the playfield.
- Chord tel. → Arena: warns in · Telegraph visuals appear in the arena.
- Radial tel. → Arena: warns in · Telegraph visuals appear in the arena.
- Backend CLI → Processor: orchestrates · Configures and runs analysis stages.
- Processor → Record format: emits · Produces trace data and analysis results.
- Audio input → Processor: feeds · Raw audio is analyzed into events.
- Record format → Demo traces: serializes as · Trace output can be stored and replayed.
- Demo traces → Director: replays into · Demo playback feeds the gameplay coordinator.
- Visual assets → Main app: skins · Themes, shaders, and fonts shape presentation.
- Visual assets → Effects: supports · Effects use shared visual resources.