From 802e97ee695de1bc8657c5cbca653bb2f13b90a8 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Mon, 9 Feb 2026 15:35:14 +0100
Subject: docs: Condense essential context files (856→599 lines)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extract detailed examples and untriaged tasks to on-demand docs.
Created BACKLOG.md, ARCHITECTURE.md, CODING_STYLE.md, TOOLS_REFERENCE.md.
Reduces always-loaded token budget by 30% while preserving all information.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 doc/ARCHITECTURE.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 doc/ARCHITECTURE.md

(limited to 'doc/ARCHITECTURE.md')

diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md
new file mode 100644
index 0000000..1a32300
--- /dev/null
+++ b/doc/ARCHITECTURE.md
@@ -0,0 +1,60 @@
+# 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 `assets/demo.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.
-- 
cgit v1.2.3