# System architecture

> This document answers three questions for anyone changing the repository: which layer a piece of code belongs to, which folder owns it, and what it is allowed to depend on. Tune.To

Source: https://docs.tune.toys/contributors/architecture-overview/

This document answers three questions for anyone changing the repository: which layer a piece of code belongs to, which folder owns it, and what it is allowed to depend on. Tune.Toys has three durable layers: **portable authored data**, **execution and presentation**, and **creation/distribution services**. Product shells compose them. Cloud services support discovery and delivery; local audio never depends on their availability.

**Status:** the local browser, authoring, shared Frame runtime, Rust compiler/engine/ABI, and source/catalog packages are implemented. The development API, releases, agent adapter and native Player core are implemented. Managed hosting and full journey qualification remain open; see [implementation status](https://github.com/joshstovall/TuneToys/blob/main/docs/delivery/implementation-status.md).

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#FAFAF7', 'primaryTextColor': '#1C1C1B', 'primaryBorderColor': '#1C1C1B', 'lineColor': '#64645F', 'fontFamily': 'DM Sans, Inter, system-ui, sans-serif'}}}%%
flowchart TB
  WEB["Web editor and community"] --> AUTHOR["Authoring API<br/>revisions and proposals"]
  AGENT["In-app agent<br/>later CLI and MCP"] --> AUTHOR
  AUTHOR --> SOURCE[("Toy source<br/>definitions · ports · controls · Frames")]
  SOURCE --> COMPILER["Compiler<br/>resolve · validate · admit · prepare"]
  COMPILER --> ENGINE["Shared DSP core"]
  SOURCE --> FRAMES["Shared Frame renderer"]
  FRAMES <--> LIVE["Running-instance protocol"]
  LIVE <--> ENGINE
  ENGINE --> BROWSER["WASM + AudioWorklet host"]
  ENGINE --> NATIVE["Native ABI + JUCE shell"]
  NATIVE --> PLAYER["TuneToys Player plugin"]
  NATIVE --> EXPORT["Independent plugin export"]
  SOURCE --> RELEASE["Immutable release pipeline"]
  RELEASE --> CDN["Managed or self-hosted web publication"]
  RELEASE --> LIBRARY["Catalog · account library · install cache"]
  LIBRARY --> PLAYER

  classDef source fill:#F0442E,stroke:#1C1C1B,color:#FAFAF7
  classDef shared fill:#DCEBDD,stroke:#1C1C1B,color:#1C1C1B
  classDef host fill:#DED8F0,stroke:#1C1C1B,color:#1C1C1B
  class SOURCE source
  class AUTHOR,COMPILER,ENGINE,FRAMES,LIVE,RELEASE shared
  class WEB,AGENT,BROWSER,NATIVE,PLAYER,EXPORT,CDN,LIBRARY host
```

Arrows describe the complete intended boundaries, not a claim that every edge is qualified end to end.

## Ownership

| Layer                   | Location                                                                                                                                                                                              | Owns                                                        |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| Product shells          | [`apps/web`](https://github.com/joshstovall/TuneToys/blob/main/apps/web/README.md), [`apps/player-plugin`](https://github.com/joshstovall/TuneToys/blob/main/apps/player-plugin/README.md), [`apps/desktop`](https://github.com/joshstovall/TuneToys/blob/main/apps/desktop/README.md) (Editor and Installer; release qualification open) | Routes/windows, user flows, host lifecycle                  |
| Authoring               | [`packages/authoring`](https://github.com/joshstovall/TuneToys/blob/main/packages/authoring/README.md), [`packages/editor`](https://github.com/joshstovall/TuneToys/blob/main/packages/editor/README.md) (extraction pending; editor UI lives in `apps/web`)                                  | Atomic edits, history, candidates; graph editing UI         |
| Portable contracts      | [`packages/toy-format`](https://github.com/joshstovall/TuneToys/blob/main/packages/toy-format/README.md), [`packages/runtime-protocol`](https://github.com/joshstovall/TuneToys/blob/main/packages/runtime-protocol/README.md)                                                                | Source grammar; instance control/event protocol             |
| Presentation            | [`packages/frame-runtime`](https://github.com/joshstovall/TuneToys/blob/main/packages/frame-runtime/README.md)                                                                                                                                    | Shared React renderer, widgets, bindings, accessibility     |
| Browser execution       | [`packages/runtime-web`](https://github.com/joshstovall/TuneToys/blob/main/packages/runtime-web/README.md)                                                                                                                                        | Worklet, WASM loading, browser I/O, generation handoff      |
| Processing              | [`crates/compiler`](https://github.com/joshstovall/TuneToys/blob/main/crates/compiler/README.md), [`crates/engine`](https://github.com/joshstovall/TuneToys/blob/main/crates/engine/README.md), [`crates/engine-ffi`](https://github.com/joshstovall/TuneToys/blob/main/crates/engine-ffi/README.md)                                      | Admission/programs, DSP/state, native ABI                   |
| Native host integration | [`native/plugin-shell`](https://github.com/joshstovall/TuneToys/blob/main/native/plugin-shell/README.md)                                                                                                                                          | JUCE buses, transport, gestures, state, embedded web bridge |
| Distribution            | [`services/api`](https://github.com/joshstovall/TuneToys/blob/main/services/api/README.md), [`services/worker`](https://github.com/joshstovall/TuneToys/blob/main/services/worker/README.md) (listing assets; builds planned), [`exporters/*`](https://github.com/joshstovall/TuneToys/blob/main/exporters/README.md)                     | Auth/catalog/library; isolated jobs; target packaging       |
| Extension interface     | [`packages/sdk`](https://github.com/joshstovall/TuneToys/blob/main/packages/sdk/README.md), [`packages/node-catalog`](https://github.com/joshstovall/TuneToys/blob/main/packages/node-catalog/README.md)                                                                                      | Public developer APIs and node/component discovery          |

## Dependency rules

Pure data contracts sit at the bottom and import nothing above them.

| Layer            | May depend on                             | Must not depend on                                  |
| ---------------- | ----------------------------------------- | --------------------------------------------------- |
| Contracts        | Nothing above                             | React, browser/OS APIs, databases, account services |
| Authoring        | Contracts                                 | React, account databases                            |
| Editor UI        | Authoring, contracts                      | Mutating the graph behind authoring's back          |
| Frames           | Running-instance interface, public params | The editor                                          |
| Runtime adapters | Compiler outputs, contracts               | The account service                                 |
| Apps             | Any shared package                        | Other apps                                          |
| Packages         | Other packages                            | Apps                                                |
| Rust DSP         | Its own crates                            | The website, JUCE, Electron, any model vendor       |

**The compiler may allocate off the audio thread; the prepared engine may not allocate during render.** The FFI adapter presents a small C ABI. JUCE remains C++ host integration, and the same native shell serves both Player and independent exports.

The backend begins as a modular monolith: identity, projects, releases, library, discovery and later commerce modules in one API deployment and one relational database. Long builds and renders belong in a separately isolated worker backed by durable jobs and object storage. Add services only when security, scaling or ownership demonstrates a need. AWS is selected: the initial hosting plan is one Lightsail/PostgreSQL server, private S3 for media and backups, and SES. The existing S3/SES adapters and PostgreSQL cutover support the next steps; further hosting services are deferred until needed. See [AWS architecture](https://github.com/joshstovall/TuneToys/blob/main/docs/architecture/aws.md) and the [media library](https://github.com/joshstovall/TuneToys/blob/main/docs/specs/media-library.md).

## Data authority

| Data                                              | Authority                                  | Mutability                |
| ------------------------------------------------- | ------------------------------------------ | ------------------------- |
| Source                                            | Project/revision store                     | Mutable through revisions |
| Releases and assets                               | Content digest                             | Immutable                 |
| Catalog entries, visibility, library annotations  | Relational database                        | Mutable                   |
| Search indexes, thumbnails                        | Derived from the above                     | Rebuildable               |
| Installed releases                                | Local verified cache of pinned releases    | Replaceable, never edited |
| DAW sessions                                      | Self-contained recall state in the project | Owned by the host project |
| Device selection, secrets, grants, remote pairing | Host-local only                            | Never portable            |

A running instance has its own generation and live values. Saving a project default, changing a runtime parameter, publishing a release, bookmarking a Toy and restoring a DAW session are separate operations. **A catalog edit or a canvas move can never change an active sound.**

## Implementation

- Contracts: [`packages/toy-format`](https://github.com/joshstovall/TuneToys/blob/main/packages/toy-format/README.md), [`packages/runtime-protocol`](https://github.com/joshstovall/TuneToys/blob/main/packages/runtime-protocol/README.md), [`packages/node-catalog`](https://github.com/joshstovall/TuneToys/blob/main/packages/node-catalog/README.md)
- Execution: [`crates/`](https://github.com/joshstovall/TuneToys/blob/main/crates/README.md), [`packages/runtime-web`](https://github.com/joshstovall/TuneToys/blob/main/packages/runtime-web/README.md), [`native/plugin-shell`](https://github.com/joshstovall/TuneToys/blob/main/native/plugin-shell/README.md)
- Presentation and authoring: [`packages/frame-runtime`](https://github.com/joshstovall/TuneToys/blob/main/packages/frame-runtime/README.md), [`packages/authoring`](https://github.com/joshstovall/TuneToys/blob/main/packages/authoring/README.md)
- Shells and services: [`apps/`](https://github.com/joshstovall/TuneToys/blob/main/apps/README.md), [`services/`](https://github.com/joshstovall/TuneToys/blob/main/services/README.md), [`exporters/`](https://github.com/joshstovall/TuneToys/blob/main/exporters/README.md)

## Related

- [Execution and optimization](https://docs.tune.toys/contributors/execution/)
- [Frames and interface composition](https://docs.tune.toys/contributors/frames/)
- [Publishing, Player and remote control](https://docs.tune.toys/contributors/distribution/)
- [Trust and service boundaries](https://docs.tune.toys/contributors/security/)
- [Architecture decisions](https://docs.tune.toys/contributors/decisions/)
- [MVP scope](https://docs.tune.toys/contributors/mvp/) and [implementation status](https://github.com/joshstovall/TuneToys/blob/main/docs/delivery/implementation-status.md)