# airencracken/songstead architecture

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

- Interactive diagram: https://gitdiagram.com/airencracken/songstead
- Repository: https://github.com/airencracken/songstead

## Overview

Songstead is a self-hosted music-recommendation inbox for small communities. Members submit music links and choose an audience; the server previews metadata, stores recommendations, and presents Recent, shelf/history, search, listening feedback, likes, comments and timestamped annotations. Owners also manage accounts, invitations and settings, while users can export history and operators can back up or restore data. The graph follows the documented user workflow and sampled server/store calls; several README capabilities have only directory-level paths because their implementation files were not excerpted.

Main entry points: [`internal/web/music.go`](https://github.com/airencracken/songstead/blob/master/internal/web/music.go) (Recommendations), [`cmd/songstead/main.go`](https://github.com/airencracken/songstead/blob/master/cmd/songstead/main.go) (CLI and server), [`internal/store/store.go`](https://github.com/airencracken/songstead/blob/master/internal/store/store.go) (SQLite store), [`internal/web/web.go`](https://github.com/airencracken/songstead/blob/master/internal/web/web.go) (HTTP application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_cli["CLI and server<br/>[main.go]"]
  node_http["HTTP application<br/>[web.go]"]
end

subgraph group_experience["Member experience"]
  node_music["Recommendations<br/>[music.go]"]
  node_posts["Post management<br/>[posts.go]"]
  node_profiles["Profiles<br/>[profiles.go]"]
  node_search["Search<br/>[search.go]"]
  node_admin["Administration<br/>[admin.go]"]
  node_integrations["Discussion links<br/>[integration.go]"]
end

subgraph group_domain["Music domain"]
  node_preview["Link preview<br/>[previews.go]"]
  node_media["Music metadata<br/>[metadata.go]"]
  node_annotations["Timestamp comments<br/>[annotations.go]"]
end

subgraph group_persistence["Persistence and operations"]
  node_recommendation_store["Inbox and music state<br/>[inbox.go]"]
  node_search_store["Search queries<br/>[search.go]"]
  node_account_store["Accounts and access<br/>[administration.go]"]
  node_store[("SQLite store<br/>[store.go]")]
  node_export["History export<br/>[export.go]"]
  node_snapshots["Snapshot restore<br/>[snapshot.go]"]
  node_backup["Automatic backups"]
  node_other_store["Member data"]
end

node_member(("Community member"))
node_owner(("Owner"))

node_member -->|"uses"| node_http
node_owner -->|"administers"| node_http
node_cli -.->|"serves"| node_http
node_http -.->|"routes requests"| node_music
node_http -.->|"routes requests"| node_admin
node_music -.->|"stores posts"| node_recommendation_store
node_music -.->|"requests previews"| node_preview
node_preview -->|"fetches metadata"| node_media
node_music -.->|"edits posts"| node_posts
node_posts -.->|"updates posts"| node_recommendation_store
node_search -->|"searches music"| node_search_store
node_search -->|"searches comments"| node_other_store
node_admin -->|"manages accounts"| node_account_store
node_integrations -->|"uses timestamps"| node_annotations
node_music -.->|"shows annotations"| node_annotations
node_profiles -.->|"loads profiles"| node_other_store
node_music -.->|"loads member data"| node_other_store
node_cli -->|"opens store"| node_store
node_cli -->|"restores snapshot"| node_snapshots
node_cli -->|"starts backups"| node_backup
node_backup -->|"takes snapshots"| node_store
node_cli -.->|"exports history"| node_export
node_store -.->|"persists inbox"| node_recommendation_store
node_store -.->|"persists accounts"| node_account_store
node_store -.->|"persists member data"| node_other_store

click node_cli "https://github.com/airencracken/songstead/blob/master/cmd/songstead/main.go"
click node_http "https://github.com/airencracken/songstead/blob/master/internal/web/web.go"
click node_music "https://github.com/airencracken/songstead/blob/master/internal/web/music.go"
click node_posts "https://github.com/airencracken/songstead/blob/master/internal/web/posts.go"
click node_profiles "https://github.com/airencracken/songstead/blob/master/internal/web/profiles.go"
click node_search "https://github.com/airencracken/songstead/blob/master/internal/web/search.go"
click node_admin "https://github.com/airencracken/songstead/blob/master/internal/web/admin.go"
click node_integrations "https://github.com/airencracken/songstead/blob/master/internal/web/integration.go"
click node_preview "https://github.com/airencracken/songstead/blob/master/internal/web/previews.go"
click node_media "https://github.com/airencracken/songstead/blob/master/internal/media/metadata.go"
click node_annotations "https://github.com/airencracken/songstead/blob/master/internal/store/annotations.go"
click node_recommendation_store "https://github.com/airencracken/songstead/blob/master/internal/store/inbox.go"
click node_search_store "https://github.com/airencracken/songstead/blob/master/internal/store/search.go"
click node_account_store "https://github.com/airencracken/songstead/blob/master/internal/store/administration.go"
click node_store "https://github.com/airencracken/songstead/blob/master/internal/store/store.go"
click node_export "https://github.com/airencracken/songstead/blob/master/internal/store/export.go"
click node_snapshots "https://github.com/airencracken/songstead/blob/master/internal/store/snapshot.go"
click node_backup "https://github.com/airencracken/songstead/blob/master/cmd/songstead/automatic_backup.go"
click node_other_store "https://github.com/airencracken/songstead/tree/master/internal/store"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_http toneBlue
class node_music,node_posts,node_profiles,node_search,node_admin,node_integrations toneAmber
class node_preview,node_media,node_annotations toneMint
class node_recommendation_store,node_search_store,node_account_store,node_store,node_export,node_snapshots,node_backup,node_other_store toneRose
class node_member,node_owner toneIndigo
```

## Components

### Application entry

- [CLI and server](https://github.com/airencracken/songstead/blob/master/cmd/songstead/main.go): `cmd/songstead/main.go`
- [HTTP application](https://github.com/airencracken/songstead/blob/master/internal/web/web.go): `internal/web/web.go`

### Member experience

- [Recommendations](https://github.com/airencracken/songstead/blob/master/internal/web/music.go): `internal/web/music.go`
- [Post management](https://github.com/airencracken/songstead/blob/master/internal/web/posts.go): `internal/web/posts.go`
- [Profiles](https://github.com/airencracken/songstead/blob/master/internal/web/profiles.go): `internal/web/profiles.go`
- [Search](https://github.com/airencracken/songstead/blob/master/internal/web/search.go): `internal/web/search.go`
- [Administration](https://github.com/airencracken/songstead/blob/master/internal/web/admin.go): `internal/web/admin.go`
- [Discussion links](https://github.com/airencracken/songstead/blob/master/internal/web/integration.go): `internal/web/integration.go`

### Music domain

- [Link preview](https://github.com/airencracken/songstead/blob/master/internal/web/previews.go): `internal/web/previews.go`
- [Music metadata](https://github.com/airencracken/songstead/blob/master/internal/media/metadata.go): `internal/media/metadata.go`
- [Timestamp comments](https://github.com/airencracken/songstead/blob/master/internal/store/annotations.go): `internal/store/annotations.go`

### Persistence and operations

- [Inbox and music state](https://github.com/airencracken/songstead/blob/master/internal/store/inbox.go): `internal/store/inbox.go`
- [Search queries](https://github.com/airencracken/songstead/blob/master/internal/store/search.go): `internal/store/search.go`
- [Accounts and access](https://github.com/airencracken/songstead/blob/master/internal/store/administration.go): `internal/store/administration.go`
- [SQLite store](https://github.com/airencracken/songstead/blob/master/internal/store/store.go): `internal/store/store.go`
- [History export](https://github.com/airencracken/songstead/blob/master/internal/store/export.go): `internal/store/export.go`
- [Snapshot restore](https://github.com/airencracken/songstead/blob/master/internal/store/snapshot.go): `internal/store/snapshot.go`
- [Automatic backups](https://github.com/airencracken/songstead/blob/master/cmd/songstead/automatic_backup.go): `cmd/songstead/automatic_backup.go`
- [Member data](https://github.com/airencracken/songstead/tree/master/internal/store): `internal/store`

### Other components

- **Community member**
- **Owner**

## Connections

- Community member → HTTP application: uses (evidence: `README.md`)
- Owner → HTTP application: administers (evidence: `README.md`)
- CLI and server → HTTP application: serves
- HTTP application → Recommendations: routes requests
- HTTP application → Administration: routes requests
- Recommendations → Inbox and music state: stores posts
- Recommendations → Link preview: requests previews
- Link preview → Music metadata: fetches metadata (evidence: `internal/web/previews.go`)
- Recommendations → Post management: edits posts
- Post management → Inbox and music state: updates posts
- Search → Search queries: searches music (evidence: `internal/web/search.go`)
- Search → Member data: searches comments (evidence: `internal/web/search.go`)
- Administration → Accounts and access: manages accounts (evidence: `internal/web/admin.go`)
- Discussion links → Timestamp comments: uses timestamps (evidence: `internal/web/integration.go`)
- Recommendations → Timestamp comments: shows annotations
- Profiles → Member data: loads profiles (evidence: `internal/web/profiles.go`)
- Recommendations → Member data: loads member data (evidence: `internal/web/music.go`)
- CLI and server → SQLite store: opens store (evidence: `cmd/songstead/main.go`)
- CLI and server → Snapshot restore: restores snapshot (evidence: `cmd/songstead/main.go`)
- CLI and server → Automatic backups: starts backups (evidence: `cmd/songstead/main.go`)
- Automatic backups → SQLite store: takes snapshots (evidence: `cmd/songstead/automatic_backup.go`)
- CLI and server → History export: exports history
- SQLite store → Inbox and music state: persists inbox
- SQLite store → Accounts and access: persists accounts
- SQLite store → Member data: persists member data