# jpochyla/psst architecture

> Architecture diagram of the GitHub repository jpochyla/psst, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jpochyla/psst
- Repository: https://github.com/jpochyla/psst

## Overview

##### Project type and purpose
- Psst is a native desktop Spotify client written in Rust. It comprises:
- A core library (`psst-core`) handling Spotify sessions, audio retrieval/decoding/output, caching, queueing.
- A GUI app (`psst-gui`) built on Druid.
- A CLI example (`psst-cli`).
- A protocol crate (`psst-protocol`) containing Protobuf definitions and generated Rust code for Spotify’s APIs (authentication, metadata, playlists, Mercury, etc.).

##### File structure
- Top‐level crates:
- `psst-protocol` – Protobuf definitions → Rust modules
- `psst-core` – Core functionality: session, connection, audio pipeline, cache, playback queue
- `psst-gui` – UI layers: controllers, data models, view widgets, WebAPI client
- `psst-cli` – Minimal command‐line front end
- Packaging and CI:
- `.github/workflows/build.yml` – CI build & release
- `.homebrew`, `.pkg` – Homebrew formula and AppImage/Debian packaging
- Config & metadata:
- `Cargo.toml` / `Cross.toml` – Build definitions
- `README.md` – Project overview and build instructions

##### README for insights
- Confirms architecture: core + GUI + CLI + protocol.
- Lists dependencies: Rust stable, Druid (GTK/X11/Wayland), audio backends (CPAL/Cubeb), HTTPS for CDN.
- Describes features: playback, search, caching, queue, theming.

##### Final advice
- Every crate and its role.
- Layers (UI → business logic → network → storage/output).
- Do not overcomplicate: break into as many labeled components as necessary to reflect the modular Rust workspace.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Applications"
        GUI["psst-gui"]:::app
        CLI["psst-cli"]:::app
    end

    subgraph "Libraries"
        Core["psst-core"]:::lib
        Protocol["psst-protocol"]:::lib
    end

    subgraph "External Systems"
        Spotify["Spotify HTTP APIs"]:::ext
        FileSys["Local Cache (FS)"]:::ext
        AudioBackend["OS Audio / CPAL / Cubeb"]:::ext
    end

    subgraph "Packaging & CI"
        CI["GitHub Actions & Packaging"]:::tool
    end

    GUI -->|"uses"| Core
    CLI -->|"uses"| Core
    Core -->|"calls"| Protocol
    Core -->|"reads/writes"| FileSys
    Core -->|"outputs audio to"| AudioBackend
    Protocol -->|"requests/auth"| Spotify
    Core -->|"connects/auth"| Spotify
    CI -->|"builds/releases"| GUI
    CI -->|"builds/releases"| CLI
    CI -->|"builds/releases"| Core
    CI -->|"builds/releases"| Protocol

    click GUI "https://github.com/jpochyla/psst/blob/main/psst-gui/src/main.rs"
    click GUI "https://github.com/jpochyla/psst/blob/main/psst-gui/Cargo.toml"
    click Core "https://github.com/jpochyla/psst/blob/main/psst-core/src/lib.rs"
    click Core "https://github.com/jpochyla/psst/blob/main/psst-core/src/actor.rs"
    click Core "https://github.com/jpochyla/psst/blob/main/psst-core/src/cache.rs"
    click Core "https://github.com/jpochyla/psst/blob/main/psst-core/src/audio/decode.rs"
    click Core "https://github.com/jpochyla/psst/blob/main/psst-core/src/audio/output/cpal.rs"
    click Core "https://github.com/jpochyla/psst/blob/main/psst-core/src/connection/diffie_hellman.rs"
    click Protocol "https://github.com/jpochyla/psst/blob/main/psst-protocol/proto/authentication.proto"
    click Protocol "https://github.com/jpochyla/psst/blob/main/psst-protocol/src/lib.rs"
    click CLI "https://github.com/jpochyla/psst/blob/main/psst-cli/src/main.rs"
    click CLI "https://github.com/jpochyla/psst/blob/main/psst-cli/Cargo.toml"
    click CI "https://github.com/jpochyla/psst/blob/main/.github/workflows/build.yml"

    classDef app fill:#D0E6FF,stroke:#0366D6,stroke-width:1px;
    classDef lib fill:#E6FFED,stroke:#22863A,stroke-width:1px;
    classDef ext fill:#FFF5B1,stroke:#FFAB00,stroke-width:1px;
    classDef tool fill:#DDDDDD,stroke:#666666,stroke-width:1px;
```
