# Architectural Overview

Detailed system architecture for the 64k demo project.

---

## Hybrid 3D Renderer

**Core Idea**: Uses standard rasterization to draw proxy hulls (boxes), then raymarches inside the fragment shader to find the exact SDF surface.

**Transforms**: Uses `inv_model` matrices to perform all raymarching in local object space, handling rotation and non-uniform scaling correctly.

**Shadows**: Instance-based shadow casting with self-shadowing prevention (`skip_idx`).

---

## Sequence & Effect System

**Effect**: Abstract base for visual elements. Supports `compute` and `render` phases.

**Sequence**: Timeline of effects with start/end times.

**MainSequence**: Top-level coordinator and framebuffer manager.

**seq_compiler**: Transpiles workspace `timeline.seq` into C++ `timeline.cc`.

---

## Asset & Build System

**asset_packer**: Embeds binary assets (like `.spec` files) into C++ arrays.

**Runtime Manager**: O(1) retrieval with lazy procedural generation support.

**Automation**: `gen_assets.sh`, `build_win.sh`, and `check_all.sh` for multi-platform validation.

---

## Audio Engine

### Synthesis
Real-time additive synthesis from spectrograms via FFT-based IDCT (O(N log N)). Stereo output (32kHz, 16-bit, interleaved L/R). Uses orthonormal DCT-II/DCT-III transforms with Numerical Recipes reordering method.

### Variable Tempo
Music time abstraction with configurable tempo_scale. Tempo changes don't affect pitch.

### Event-Based Tracker
Individual TrackerEvents trigger as separate voices with dynamic beat calculation. Notes within patterns respect tempo scaling.

### Backend Abstraction
`AudioBackend` interface with `MiniaudioBackend` (production), `MockAudioBackend` (testing), and `WavDumpBackend` (offline rendering).

### Dynamic Updates
Double-buffered spectrograms for live thread-safe updates.

### Procedural Library
Melodies and spectral filters (noise, comb) generated at runtime.

### Pattern System
TrackerPatterns contain lists of TrackerEvents (beat, sample_id, volume, pan). Events trigger individually based on elapsed music time.