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.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.

%%{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#

Dependency rules#

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

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 and the media library.

Data authority#

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, packages/runtime-protocol, packages/node-catalog
• Execution: crates/, packages/runtime-web, native/plugin-shell
• Presentation and authoring: packages/frame-runtime, packages/authoring
• Shells and services: apps/, services/, exporters/

Related#

• Execution and optimization
• Frames and interface composition
• Publishing, Player and remote control
• Trust and service boundaries
• Architecture decisions
• MVP scope and implementation status