> ## Documentation Index
> Fetch the complete documentation index at: https://songbird.studiocollective.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding

# Onboarding

Welcome to Songbird! This guide will help you get up and running as a new contributor.

## Architecture

Songbird is **pure Rust + React/TypeScript** on Tauri v2 — there is no C++ or JUCE; that migration is complete. The Rust backend lives in `rust/` (a Cargo workspace) and the React frontend in `react_ui/`.

## Setup

Follow the instructions in [`install.md`](https://github.com/studiocollective/songbird-chirp/blob/rust/install.md) at the repo root. It covers prerequisites, submodule init, patching, building, and verification — and works with LLM coding agents out of the box.

## Project Structure Overview

| Directory   | Description                                         |
| ----------- | --------------------------------------------------- |
| `rust/`     | Rust backend (Cargo workspace)                      |
| `react_ui/` | React frontend (Vite + TypeScript + Tailwind)       |
| `server/`   | Collaboration WebSocket server (Node.js)            |
| `docs/`     | Architecture docs (Mintlify)                        |
| `files/`    | Sample `.bird` projects, MIDI files, plugin configs |
| `utils/`    | Build scripts and shell utilities                   |
| `eval/`     | LLM evaluation framework for the AI copilot         |

### Rust Crate Map

The `rust/crates/` directory contains:

| Crate               | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `songbird-engine`   | Core audio engine — graph, transport, scheduling, mixer      |
| `songbird-plugins`  | 16 stock DSP plugins (synths, effects)                       |
| `songbird-clips`    | `.bird` format tokenizer, parser, and serializer             |
| `songbird-export`   | Offline rendering (master mixdown, stem export)              |
| `songbird-record`   | Audio and MIDI recording                                     |
| `songbird-state`    | State management, command dispatch, undo/redo, collaboration |
| `songbird-sync`     | Sync engine — channels, routing, transports, guards          |
| `songbird-host-ffi` | FFI bridge for hosting VST3/AU plugins                       |
| `songbird-app`      | Tauri v2 desktop app with IPC commands                       |
| `songbird-cli`      | CLI tool for batch rendering and validation                  |
| `songbird-headless` | WebSocket server for headless deployments                    |

## Key Concepts to Learn

* **[Linear Automation](/linear-automation)** — How work flows through the Linear board: moving a card between columns drives an automated agent action (planning, review, execution, merge). Read this before picking up your first ticket.
* **[`.bird` notation](/bird)** — The text-based music format at the heart of Songbird. Understand this first.
* **[Sync Engine](/sync-engine)** — How React, Rust, and Git stay in sync.
* **[Collaboration](/collaboration)** — Git-based collaboration with real-time multiplayer cursors (WIP).
* **Tauri IPC** — The React UI communicates with the Rust backend via Tauri's typed IPC commands. Each command returns `IpcResult<T>`.
* **Real-time audio** — The engine uses a lock-free, zero-allocation audio callback with pre-allocated buffers and `SpscRingBuffer` for UI communication.

## Branches

| Branch | Purpose                                                             |
| ------ | ------------------------------------------------------------------- |
| `rust` | Active development branch — cut branches and open PRs against this. |
| `main` | Stable demo branch. Not where new work lands.                       |

All new work should branch off `rust`.

## The Tree of Code

Not all code carries the same risk. Think of the codebase as a tree — the closer to the roots, the more caution is required.

**Roots** — Core foundation. Breaking these breaks everything.

* *Examples:* App shell, install scripts, base of the audio engine, sync engine.
* Discuss changes in advance, overcommunicate, heavy test coverage, code review, QA thoroughly.

**Trunk** — Code everyone else relies on. Core features.

* *Examples:* Tracks, plugin hosting, playback, frequently used components, UI theme.
* Overcommunicate, heavy test coverage, code review, QA thoroughly.

**Branches** — Ancillary features, prototypes, or features that don't impact most users.

* *Examples:* Export options, CLI tool, niche plugin UIs.
* Test coverage, use best judgement about code review, QA.

**Leaves** — Small, self-contained things that won't break other parts of the app.

* *Examples:* Tooltips, cosmetic tweaks, docs, one-off scripts.
* Let the LLMs go wild and have fun :)

## Development Workflow

1. Branch off `rust` in Devin/Antigravity/Claude Code (or any other tool).
2. Write tests first — define success conditions before implementation.
3. Implement against those tests.
4. QA features and core functionality (e.g., don't break playback while moving fast).
5. Commit and submit a PR targeting `rust`.
6. Request human review (reviewers may use agents).

## Useful Commands

| Command               | Description                                    |
| --------------------- | ---------------------------------------------- |
| `./utils/build-rs`    | Standard build for local testing               |
| `./utils/release-rs`  | Compiled frontend for packaged builds          |
| `./utils/validate.sh` | Run all validation (Rust + TS + lint + vitest) |

## Next Steps

* Read the [Introduction](/index) for an architecture overview.
* Explore the [React UI](/react_ui) docs for frontend details.
* Check the [Roadmap](/roadmap) to see what's in progress.
* Look at the [Keyboard Shortcuts](/user_manual/shortcuts) to navigate the app efficiently.
* Read `rust/ARCHITECTURE.md` for a detailed reference of the Rust engine internals.