# gonzo-engineering/soli architecture

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

- Interactive diagram: https://gitdiagram.com/gonzo-engineering/soli
- Repository: https://github.com/gonzo-engineering/soli

## Overview

##### Project type and purpose
- This is a full-stack, monorepo-style music-streaming platform (“Soli”) comprising:
- A public SvelteKit "app" (the user-facing web player and content browser)
- A SvelteKit "dashboard" (artist/admin portal)
- A SvelteKit "api" (serverless endpoints for data, payments, media handling)
- A standalone "payroll" script for periodic musician payouts
- A "shared" folder with common types, config, and utilities
- The README’s key goal: build a streaming service that fairly remunerates musicians via transparent, decentralized micropayments.

##### File structure
- Top-level dirs:
- api/ – SvelteKit server with server-only hooks, route handlers, integration w/ Supabase (database/auth), Pinata (IPFS media), Stripe (payments)
- app/ – Public SvelteKit site; UI components, remote-function wrappers that call api routes
- dashboard/ – Artist/admin SvelteKit site; form components, music & stats views, uses same shared utilities
- payroll/ – Node/TS script to query earnings and dispatch payouts (likely via Supabase & Stripe SDK)
- shared/ – Shared code: config, types, utils, CSS resets
- Each SvelteKit project has its own config (svelte.config.js, tsconfig.json), routes/, lib/ (client vs server code), and static assets.
- CI/workflows and Netlify/Vercel configs indicate serverless deployments.

##### README for additional insights
- Emphasis on transparency, decentralization, direct remuneration.

a. Main components
– Public Web App (SvelteKit “app”)
– Artist/Admin Dashboard (SvelteKit “dashboard”)
– API Layer (SvelteKit “api” routes + server hooks)
– Payroll Service (CLI script)
– Database/Auth (Supabase)
– Media Storage (Pinata/IPFS)
– Payment Processor (Stripe)
– CI/CD & Hosting (Netlify/Vercel/GitHub Actions)

b. Relationships & interactions
1. Browser → Public Web App & Dashboard: UI served via CDN/serverless
2. UI → API Layer: remote fetch calls (endpoints under api/src/routes)
3. API Layer ↔ Supabase: CRUD for tracks, users, collections, auth
4. API Layer ↔ Pinata: upload/fetch audio files & metadata to IPFS
5. API Layer ↔ Stripe: create checkout sessions, handle webhooks, track payments
6. Payroll Script ↔ Supabase: read aggregated balances
7. Payroll Script ↔ Stripe: issue payouts to artists
8. CI/CD → deploy each SvelteKit target (app, dashboard, api)

c. Architectural patterns / design principles
– Monorepo with shared libs for DRY config, types & utils
– SvelteKit used uniformly (SSR + API routes)
– “Remote functions” pattern in frontends (thin wrappers around fetch to api)
– Separation of concerns: UI, business logic (api), external services
– Serverless / FaaS deployment model

d. Key technologies/frameworks
– SvelteKit (UI & API routes)
– Supabase (Postgres-based DB + Auth)
– Pinata (IPFS pinning service)
– Stripe (payments & webhooks)
– Node/TypeScript for payroll script
– GitHub Actions / Netlify / Vercel for CI/CD

##### Detail
- Remote-Functions folder in each UI component grouping

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        App["Public Web App\n(SvelteKit app)"]:::ui
        Dashboard["Artist/Admin Dashboard\n(SvelteKit dashboard)"]:::ui
    end

    %% Server/API Layer
    subgraph "Server/API Layer"
        API["API\n(SvelteKit serverless functions)"]:::api
    end

    %% Shared Library
    Shared["Shared Library\n(config, types, utils, styles)"]:::shared

    %% Payroll Service
    Payroll["Payroll Service\n(CLI Script)"]:::payroll

    %% External Services
    subgraph "External Services"
        Supabase[(Supabase DB/Auth)]:::external
        Pinata[(Pinata/IPFS)]:::external
        Stripe[(Stripe Payments)]:::external
    end

    %% CI/CD
    CI["CI/CD & Hosting\n(GitHub Actions, Netlify, Vercel)"]:::ci

    %% Connections
    App -->|"fetch API"| API
    Dashboard -->|"fetch API"| API
    API -->|"CRUD & Auth"| Supabase
    API -->|"upload/fetch media"| Pinata
    API -->|"payment sessions & webhooks"| Stripe
    Payroll -->|"read balances"| Supabase
    Payroll -->|"issue payouts"| Stripe
    CI -->|"deploy app"| App
    CI -->|"deploy dashboard"| Dashboard
    CI -->|"deploy api"| API
    Shared --> App
    Shared --> Dashboard
    Shared --> API

    %% Click Events
    click App "https://github.com/gonzo-engineering/soli/tree/main/app/"
    click Dashboard "https://github.com/gonzo-engineering/soli/tree/main/dashboard/"
    click API "https://github.com/gonzo-engineering/soli/tree/main/api/"
    click Payroll "https://github.com/gonzo-engineering/soli/tree/main/payroll/"
    click Shared "https://github.com/gonzo-engineering/soli/tree/main/shared/"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0288D1,color:#000
    classDef api fill:#D0FFD6,stroke:#2E7D32,color:#000
    classDef shared fill:#FFF4C2,stroke:#F9A825,color:#000
    classDef external fill:#E0E0E0,stroke:#616161,color:#000
    classDef payroll fill:#FFE0B2,stroke:#EF6C00,color:#000
    classDef ci fill:#F8BBD0,stroke:#C2185B,color:#000
```
