C4 Level 2 — Container diagram

C4 Level 2 — Container diagram

Diagram

C4Container
  title Container Diagram — Rymflux v1

  Person(listener, "Listener", "End user consuming audio")

  System_Boundary(rymflux, "Rymflux Desktop App") {
    Container(svelte_shell, "Shell UI", "Svelte + TypeScript", "Navigation, Home/Lobby, mini-player, room registry")
    Container(music_room, "Music Room", "Svelte + TypeScript", "Browse albums/artists/genres, search, player expansion, queue view")

    Container(backend, "Rust Backend", "Rust (Tauri)", "Single process hosting all core services")
    ContainerDb(sqlite, "Library Database", "SQLite", "library_items, content_resolution, playlists, playback_history")
  }

  System_Ext(plugin_proc, "Plugin Processes", "External executables (Python, Go, etc.)")
  System_Ext(audio_dev, "Audio Output", "OS audio device")

  Rel(listener, svelte_shell, "Interacts with", "GUI")
  Rel(svelte_shell, music_room, "Contains", "Svelte component tree")
  Rel(svelte_shell, backend, "Commands + events", "Tauri IPC bridge")

  Rel(backend, plugin_proc, "stdin/stdout JSON-RPC", "Launch on demand, idle timeout")
  Rel(backend, audio_dev, "Decoded PCM buffers", "phonic (cpal) output stream")
  Rel(backend, sqlite, "Reads/writes", "rusqlite")

Backend services (within the Rust process)

These are logical modules within the single Rust process, not separate deployable units:

┌────────────────────────────────────────────────────┐
│                    Rust Backend                     │
│                                                    │
│  ┌────────────────┐  ┌────────────────────┐       │
│  │ Plugin          │  │ Search             │       │
│  │ Runtime         │  │ Manager            │       │
│  │                 │  │                    │       │
│  │ • Discovery     │  │ • Dispatch         │       │
│  │ • Lifecycle     │  │ • Timeout          │       │
│  │ • IPC bridge    │  │ • Merge/dedup      │       │
│  │ • stderr capt.  │  │ • Config           │       │
│  └───────┬─────────┘  └─────┬──────────────┘       │
│          │                  │                       │
│          ▼                  ▼                       │
│  ┌────────────────┐  ┌────────────────────┐       │
│  │ Playback        │  │ Library            │       │
│  │ Engine          │  │ Service            │       │
│  │                 │  │                    │       │
│  │ • phonic        │  │ • rusqlite         │       │
│  │ • symphonia(w)  │  │ • Favorites        │       │
│  │ • rubato(w)     │  │ • Playlists        │       │
│  │ • cpal(w)       │  │                    │       │
│  │ • Queue control │  │ • History          │       │
│  └────────────────┘  └─────┬──────────────┘       │
│                             │                       │
│                             ▼                       │
│                    ┌────────────────┐               │
│                    │    SQLite      │               │
│                    │    (file)      │               │
│                    └────────────────┘               │
└────────────────────────────────────────────────────┘

Service responsibilities

Container interaction patterns

Search flow

Listener types query
       |
       v
Svelte Shell invoke("start_search", { query: "..." })
       |
       v
Rust: Search Manager
       | tokio::select! across N plugin processes
       +-- Plugin A responds -> emit("search_result", { plugin: "A", results: [...] })
       +-- Plugin B times out -> emit("search_error", { plugin: "B", error: "timeout" })
       +-- All done -> emit("search_done", { total: 42 })
       |
       v
Svelte Shell / Music Room
       +-- listen("search_result") -> append + deduplicate results
       +-- listen("search_error") -> show per-plugin notification
       +-- listen("search_done") -> show "N results from M plugins"

Playback flow

Listener presses play on a track in Music Room
       |
       v
Music Room resolve content UUID -> invoke("resolve_content", { id: "..." })
       |
       v
Rust: Library Service -> content_resolution table -> (plugin_id, foreign_id)
       |
       v
Rust: Plugin Runtime -> send JSON-RPC stream request to plugin
       |
       v
Plugin returns {"url": "https://...", "content_type": "audio/mpeg"}
       |
       v
Rust: Playback Engine -> phonic plays (symphonia decodes -> rubato resamples -> cpal outputs)
       |
       v
Rust emits "playback_state" -> Svelte mini-player updates

Startup flow

App launches (Tauri)
       |
       v
Rust: Plugin Runtime -> scan ~/.rymflux/plugins/
       |
       +-- Parse each plugin.toml
       +-- Validate manifest
       +-- Register valid plugins
       |
       v
Rust: Library Service -> open SQLite, run migrations
       |
       v
Rust: emit("platform_ready", { plugins: [...] })
       |
       v
Svelte Shell -> render Home, populate room list

(w) throughout the backend diagram = wrapped by phonic. symphonia, rubato, and cpal are consumed via the phonic crate, not linked directly.

Technology decisions