# Musiquay — Architecture

## Overview

Musiquay is built on the **Nostr protocol** — a simple, open protocol for decentralized social networking based on cryptographic keypairs and relays. But Musiquay is not just a music player on Nostr. It is a social and professional network for the entire music scene, layered on top of an open event system.

The platform rests on **six core pillars** that sit on top of the infrastructure layers:

1. **The Scene Graph** — identity and relationships for every participant in the music ecosystem (see [Identity and the Scene Graph](#identity-and-the-scene-graph) below).
2. **The Event Calendar** — location-based, social-first discovery of shows, gigs, festivals, and cultural events (see [FEATURES_CALENDAR.md](./FEATURES_CALENDAR.md)).
3. **The Event Roster** — wiki-style, scene-validated records of everyone who made each event happen, plus setlists (see [FEATURES_ROSTER.md](./FEATURES_ROSTER.md)).
4. **Release Credits** — exhaustive, structured credits for recorded music: every performer, engineer, studio, label, format, and edition. Discogs meets Metal Archives meets Bandcamp (see [FEATURES_CREDITS.md](./FEATURES_CREDITS.md)).
5. **Merchandise and Physical Sales** — merch stores, record shop inventory, distro catalogs, and fan resale. Zero-fee commerce for the entire physical economy of music (see [FEATURES_MERCHANDISE.md](./FEATURES_MERCHANDISE.md)).
6. **The Services Marketplace** — structured, zero-fee matchmaking for freelance and professional work across the scene (see [FEATURES_MARKETPLACE.md](./FEATURES_MARKETPLACE.md)).

The event roster (#3) and release credits (#4) together form a **unified credits system** — the same validation model (scene police, wiki-style editing, cryptographic confirmations) applied to both live events and recorded music. Together they build the complete professional history of everyone in the scene.

The merchandise system (#5) is the **storefront** for the credits system's **catalog** — physical releases for sale link directly to their edition data, giving buyers full provenance (pressing plant, mastering engineer, catalog number) right from the product listing.

All six pillars share the same Nostr identities, the same relay infrastructure, the same social graph, and the same payment layer. They reinforce each other: the calendar creates events, the marketplace fills crew needs, the roster documents the live side, the credits document the studio side, the merch system sells the physical artifacts, and the scene graph accumulates everything into the reputation that generates more work.

The architecture is designed around five infrastructure layers:

```
┌─────────────────────────────────────────────┐
│              Client Layer                   │
│         (Web UI, Mobile Apps)               │
├─────────────────────────────────────────────┤
│             Social Layer                    │
│  (Scene Graph, Discovery, Networking)       │
├─────────────────────────────────────────────┤
│            Payment Layer                    │
│     (Lightning Network / Stripe)            │
├─────────────────────────────────────────────┤
│             Relay Layer                     │
│   (Musiquay Relay + Nostr Network)          │
├─────────────────────────────────────────────┤
│             Media Layer                     │
│       (Blossom Servers / CDN)               │
└─────────────────────────────────────────────┘
```

## MVP Scope

The initial release is a **full-stack deployment**: relay, media infrastructure, payment layer, and client applications — all shipping together.

**MVP decisions:**

- **Nostr-only identity.** Every user is a keypair from day one. There is no email/password signup in the MVP. Custodial identity management (managed keys behind an email signup flow) will be a dedicated chapter of work later, designed to lower the onboarding barrier without compromising the protocol-native foundation.
- **Full stack.** The MVP includes the relay, blossom server integration, Lightning payment infrastructure, and web client. This is not a phased rollout — the full experience ships at once.
- **Originals only.** Only original music, same as Bandcamp. Content moderation and takedown processes will be defined in a future chapter — not an MVP concern.
- **NIP reuse.** Before defining any custom event kinds or protocol extensions, the project will survey everything that already exists in the Nostr ecosystem and maximize reuse of existing NIPs and specs. Custom NIPs are created only when genuinely needed.

## Nostr Fundamentals

### How Nostr Works

Nostr is a protocol, not a platform. The key concepts:

- **Identity** is a cryptographic keypair. Each user is identified by a public key (npub) and signs events with their private key (nsec). There are no usernames or passwords managed by a server — identity is self-sovereign.
- **Events** are the atomic unit of data. An event is a JSON object signed by the author's private key. Events have a `kind` field that determines their type (text note, metadata, contact list, etc.). Musiquay will use existing music-related event kinds where they exist and define new ones only when necessary.
- **Relays** are servers that receive, store, and forward events. Clients connect to relays via **WebSockets** and subscribe to events matching specific filters. Relays are interchangeable — the same event can exist on many relays simultaneously.
- **Subscriptions** are how clients request data. A client connects to a relay, sends a filter (e.g., "give me all events of kind X from pubkey Y since timestamp Z"), and the relay streams matching events in real time.

### Why Nostr for Music — and for the Scene

Nostr was designed for social networking, which makes it a natural fit not just for music distribution but for the entire social and professional layer Musiquay aims to build.

- **Every participant is a first-class identity.** A venue, a sound engineer, a photographer, and a band are all just keypairs publishing events. The protocol doesn't privilege one type of participant over another.
- **Playlists** are just events — lists of references to track events. They can be public, private (encrypted), or shared with specific keys. All versioning and access control is handled at the protocol level.
- **Profiles** are metadata events. Musiquay extends standard Nostr profiles with scene-specific fields (role, skills, location, portfolio, Lightning address) while remaining compatible with the broader Nostr network.
- **Social interaction** is native — follows, mentions, reactions, reposts, direct messages all work at the protocol level. A promoter can follow venues and artists. A photographer can tag artists in gig shots. A label can curate and publish releases. All on the same network.
- **Everything is real-time** because the transport layer is WebSockets. When an artist publishes a new track, subscribers see it immediately. When a venue posts a show, the local scene knows instantly.
- **Persistence is distributed.** Events published to multiple relays survive any single relay going offline. Users who want guaranteed persistence can pay for relay storage; casual content can be ephemeral.

## Platform Pillars

The music layer and six pillars — scene graph, event calendar, event roster, release credits, merchandise, and services marketplace — are the product-level features that define what Musiquay is. They are documented in detail across this file and dedicated feature docs:

- **Scene Graph** — the identity and relationship layer (this document, below)
- **Event Calendar** — [FEATURES_CALENDAR.md](./FEATURES_CALENDAR.md) — location-based discovery, social RSVPs, waitlists, ticket pre-sales, release countdowns. Built on NIP-52 (Calendar Events, kinds 31922/31923/31924/31925).
- **Event Roster** — [FEATURES_ROSTER.md](./FEATURES_ROSTER.md) — wiki-style, scene-validated records of every participant at every event, plus setlists linking live performance to recorded tracks. The mechanism that turns events into permanent, structured history. Built on NIP-52 (roster = the calendar event updated post-show), NIP-32 (confirmations, attestations), NIP-22 (contributions), plus the setlist kind 32213.
- **Release Credits** — [FEATURES_CREDITS.md](./FEATURES_CREDITS.md) — exhaustive structured credits for recorded music: every performer, engineer, studio, label, and edition. Per-track credits, format/edition tracking, manufacturing details. The same scene police validation as event rosters — same NIP-32 and NIP-22 mechanisms.
- **Music Layer** — [FEATURES_MUSIC.md](./FEATURES_MUSIC.md) — tracks (32210), albums (32211), playlists (32212), and play reports (3221): the recording is the identity, every Blossom encoding is an edition of it, plays are auditable.
- **Paid Access and Certified Delivery** — [FEATURES_ACCESS.md](./FEATURES_ACCESS.md) — signed membership filters (32217) gate paid assets, private purchase orders (3222) carry intent plus payment, private host-signed receipts (32218) record serves, host aggregates (32219) and publisher rollups (32220) publish totals, and BDHKE blind signatures with NUT-12 DLEQ proofs certify paid plays without identifying listeners. Includes the retailer channel model.
- **Merchandise and Physical Sales** — [FEATURES_MERCHANDISE.md](./FEATURES_MERCHANDISE.md) — artist merch stores, record shop inventory, distro catalogs, and fan resale market. Physical releases link to edition data from the credits system. Built on NIP-15 (Nostr Marketplace, kinds 30017/30018) for stores and NIP-99 (Classified Listings, kind 30402) for resale. Zero platform cut on all transactions.
- **Services Marketplace** — [FEATURES_MARKETPLACE.md](./FEATURES_MARKETPLACE.md) — structured listings for services offered and needed, zero-fee matchmaking, reputation through the scene graph. Built on NIP-99 (Classified Listings, kind 30402).

The pillars share everything: identities, social graph, relay infrastructure, media layer, and payment rails. A record shop is one Nostr identity that lists inventory (NIP-15), hosts in-store events (NIP-52), gets tagged on rosters, and connects with labels and distros — all on the same key, the same relay, the same protocol.

## Identity and the Scene Graph

This is the architectural heart of what makes Musiquay different from a simple music player. The platform models the **entire music ecosystem** as a graph of Nostr identities and their relationships.

### Participant Types

Every user is a Nostr keypair. Profile metadata indicates their role(s) in the scene. A single identity can hold multiple roles (e.g., a musician who also promotes shows and does sound engineering).

| Role | Description | Example Activity |
|------|-------------|------------------|
| **Artist / Band** | Musicians, solo or collective | Publish tracks, albums, tour dates |
| **Listener / Fan** | Music consumers and supporters | Stream, build playlists, support artists |
| **Venue** | Physical spaces for live music | List shows, capacity, technical specs, location |
| **Promoter** | Event organizers | Create and promote events, book artists |
| **Label** | Music labels, collectives | Curate rosters, publish releases, manage catalogs |
| **Agent / Manager** | Artist representation | Connect with venues and promoters |
| **Producer** | Studio producers | Showcase credits and portfolio |
| **Engineer** | Sound, mix, mastering engineers | Showcase credits and portfolio |
| **Tech Staff** | Live sound, lighting, staging | Availability, skills, past work |
| **Road Crew / Rigger** | Touring and rigging professionals | Availability, skills, tour history |
| **Designer / Illustrator** | Visual artists for album art, merch, posters | Portfolio, availability |
| **Photographer** | Music and event photographers | Portfolio, gig coverage |
| **Filmmaker** | Music video, live recording | Portfolio, showreel |
| **Record Shop** | Independent physical retail | Catalog inventory, sell new and used records, host in-store events |
| **Distro** | Distribution labels and services | Catalog carried titles, connect with labels, ship to customers and retail |
| **Merch Company** | Screen printers, merch manufacturers | Produce physical merch, get credited on products |

### Scene Relationships

The social graph isn't just "follows." It encodes professional and creative relationships:

- An **artist** is signed to a **label**
- A **venue** books through a **promoter**
- A **track** credits a **producer**, **mixer**, and **mastering engineer**
- A **show** is at a **venue**, promoted by a **promoter**, featuring **artists**, shot by a **photographer**
- A **designer** created the artwork for a **release**
- An **engineer** has a body of work spanning dozens of **artists**
- A **record shop** carries releases from dozens of **labels**
- A **distro** distributes for **labels** across territories
- A **merch company** prints T-shirts for **artists** and **festivals**

These relationships are expressed as Nostr events — taggable, queryable, and owned by the participants. They form the connective tissue that turns Musiquay from a music platform into a scene platform.

The primary mechanisms for building these relationships are the **[event roster](./FEATURES_ROSTER.md)** and **[release credits](./FEATURES_CREDITS.md)** — together forming a unified credits system. Every confirmed roster entry (live) and every confirmed release credit (studio) creates a node in the scene graph: a connection between people, a credit on a profile, a piece of professional history. Over time, the combined system builds a dense, verifiable map of who has worked with whom — on stage and in the studio — across every role in the scene.

### Discoverability

The scene graph enables powerful discovery:

- Find all shows at venues near you this week
- Find sound engineers who have worked with artists you like
- Find photographers available for gig coverage in your city
- Find all releases mastered by a specific engineer
- Find promoters who book your genre

This is the professional network the music scene has never had — and it emerges naturally from structured Nostr events rather than from a proprietary database.

## Layer Details

### 1. Relay Layer

The Musiquay relay is the core infrastructure the foundation operates. It is a Nostr relay optimized for music and scene events.

**Responsibilities:**

- Accept and validate Nostr events — music content (tracks, albums, playlists), scene activity (shows, bookings, credits), and social interaction (follows, messages, reactions).
- Store events for persistence (paid tier) or relay them transiently (free tier).
- Serve event queries with history and search capabilities.
- **Replicate to the broader Nostr network** — push all public events to major public relays so that Musiquay content is accessible from any Nostr client.

**Design considerations:**

- This is more complex than "a big Postgres and calling it a day." The relay must handle real-time WebSocket connections at scale, manage event validation and deduplication, and coordinate with media storage.
- The relay supports NIP (Nostr Implementation Possibilities) standards for interoperability. The project's NIP strategy is **reuse first** — survey the existing ecosystem thoroughly before creating anything custom.
- Event deletion requests (NIP-09) are honored on a best-effort basis — the relay will respect them, but events replicated to other relays may persist elsewhere. This is a fundamental property of distributed systems, not a bug. The mindset is: everything published can theoretically exist forever.

**Federation model:**

- Musiquay operates the primary relay but any organization or individual can run their own.
- Music festivals, labels, or collectives can operate their own relays with their own Nostr keys, receiving content and payments directly. A festival like Estoril or Janela could run their own relay and Lightning wallet, with zero dependence on Musiquay infrastructure.
- The protocol guarantees interoperability — a track published to one relay can be discovered and played from any compatible client connected to any relay that has it.

### 2. Media Layer

Audio files and artwork are not stored inside Nostr events (which are lightweight JSON). Instead, media is hosted on **Blossom servers** — the media storage layer of the Nostr ecosystem.

**Blossom (Bitcoin Lightning Object Storage Model):**

- Content-addressed media storage (files identified by hash).
- Users can upload media to any blossom server.
- Events reference media by hash/URL.
- Musiquay operates blossom server infrastructure for the community.
- Artists and other participants who want full control can host their own blossom server and simply reference their media in events.

**Streaming:**

- Audio streaming is served from blossom servers / CDN.
- No DRM, no artificial scarcity. Media is available for streaming to anyone who subscribes to the relay.
- The philosophy: "it's always possible to rip, it's not about being ultra secure, it's about facilitating fair distribution to who people actually listen to."

**Content policy:**

- Originals only. Like Bandcamp, Musiquay is for artists publishing their own work.
- Takedown processes and moderation policies are a future chapter of work — the MVP ships with a clear originals-only policy and handles edge cases as they arise.

### 3. Social Layer

The social layer is what transforms Musiquay from a music distribution tool into a home for the scene. It sits on top of the relay layer and leverages Nostr's native social primitives.

**Core capabilities:**

- **Activity feeds** — see what the people and entities you follow are doing: new releases, upcoming shows, gig photos, studio sessions, tour announcements.
- **Scene discovery** — find participants by role, location, genre, connections, and activity. The scene graph makes the invisible visible.
- **Professional networking** — credits, collaborations, bookings, and availability. A living, decentralized resume for everyone in the industry.
- **Event listings** — venues and promoters publish shows. Artists confirm appearances. Fans discover events. All as Nostr events.
- **Content sharing** — not just music. Photos from gigs, video clips, poster art, studio shots. The visual and social life of the scene.

**Social features are protocol-native:**

- Follows, reactions, reposts, and direct messages use standard Nostr NIPs.
- Scene-specific interactions (credits, bookings, event listings) use extended or custom event kinds, following the reuse-first NIP strategy.
- Everything is interoperable with the broader Nostr ecosystem — a Musiquay profile is a Nostr profile, visible from any Nostr client.

### 4. Payment Layer

Payments flow directly from listeners to artists using the **Lightning Network**, a Layer 2 protocol on Bitcoin that enables instant, near-zero-fee micropayments.

**How it works for listeners:**

- Musiquay acts as a **custodial wallet** by default. Listeners don't need to understand Bitcoin or Lightning. They see a simple interface.
- **On-ramp via Stripe:** listeners can fund their account with a credit card. The platform converts fiat to sats (Lightning units) behind the scenes. Nobody needs a crypto wallet.
- Alternatively, users who already have Lightning wallets can connect them directly (non-custodial).

**How it works for artists:**

- Each artist has a Lightning address associated with their Nostr identity.
- Artists who want full control use their own Nostr keys and their own Lightning wallet — payments go directly to them with zero platform involvement.
- Artists who prefer simplicity use the foundation's custodial infrastructure and can withdraw earnings however they choose.

**Payment distribution:**

- The listener's monthly allocation (e.g., 10,000 plays) is distributed proportionally to the artists they actually listened to.
- This is the **direct distribution model** — the opposite of Spotify's pooled royalty system.
- Lightning mini smart contracts enable this per-play micro-accounting without requiring each transaction to settle individually.

### 5. Client Layer

Musiquay develops and maintains reference client applications — but because the protocol is open, anyone can build a client that interacts with the same network.

**Reference clients:**

- **Web application** — the primary interface, shipping with the MVP.
- **Mobile applications** — for on-the-go listening and scene engagement.

**Client responsibilities:**

- Key management — generating, storing, and using Nostr keypairs. In the MVP, users manage their own keys (or use a Nostr key manager / browser extension). Custodial key management (keys managed behind an email signup) is a dedicated future chapter.
- Connecting to relays via WebSockets and managing subscriptions.
- Audio playback from blossom servers.
- Scene browsing — discovering and connecting with participants across all roles.
- Payment UI — funding account, viewing distribution, earnings dashboard.
- Playlist management — creating, sharing, importing.
- Social interaction — feeds, follows, messages, reactions.

**Third-party clients:**

- Any developer can build a Nostr client that supports Musiquay event kinds.
- Existing Nostr clients could add music and scene support.
- The protocol is the platform, not the app.

## Data Model (Event Kinds)

Musiquay's data model is expressed as Nostr events. The strategy is to **maximize reuse of existing NIPs** and only create custom event kinds when nothing suitable exists.

### Music Events

Full spec: [FEATURES_MUSIC.md](./FEATURES_MUSIC.md).

| Concept | Description | NIP Strategy |
|---------|-------------|--------------|
| **Track** | A single recording; addressable event carrying all published encodings (Blossom blobs identified by SHA-256 + codec spec), with metadata modeled on ID3/MusicBrainz tags | Custom kind 32210 |
| **Album / Release** | An ordered collection of tracks; references track event addresses. Full structured credits, format editions, and manufacturing details via [release credits system](./FEATURES_CREDITS.md). | Custom kind 32211 |
| **Playlist** | An ordered list of track references; can be public or private (NIP-44 encrypted) | Custom kind 32212, NIP-51 set conventions |
| **Play Event** | A record of a listener playing a track; used for payment distribution and play statistics | Custom kind 3221; NIP-38 kind 30315 `d:music` for the live now-playing layer |

### Scene Events

| Concept | Description | NIP Strategy |
|---------|-------------|--------------|
| **Scene Profile** | Extended Nostr profile metadata with role(s), skills, location, portfolio links, Lightning address | Extend NIP-01 metadata |
| **Credit** | Links a participant to a work (e.g., "mixed by", "artwork by", "photographed by") | Release credits 32214 / track credits 32215, plus NIP-32 labels for validation |
| **Booking** | A professional connection between promoter/venue and artist for a show | Future work, likely custom |

### Calendar Events (NIP-52)

See [FEATURES_CALENDAR.md](./FEATURES_CALENDAR.md) for full details.

| Concept | Description | NIP |
|---------|-------------|-----|
| **Date-Based Event** | All-day/multi-day events (festivals, release dates) | NIP-52, kind 31922 |
| **Time-Based Event** | Shows, gigs, listening parties with specific start/end times; includes geohash, location, participant tags | NIP-52, kind 31923 |
| **Calendar** | Collection of events (venue calendar, tour schedule, promoter season) | NIP-52, kind 31924 |
| **RSVP** | Attendance response (accepted/declined/tentative) linked to a calendar event | NIP-52, kind 31925 |
| **Waitlist Position** | Queue entry for sold-out events | NIP-52, kind 31925 — RSVP with `status: waitlist` + `position`/`joined_at` tags |
| **Release Countdown** | Future release date with subscriber notifications | Date-based event + custom tags |

### Roster Events (NIP-52 + NIP-32 + NIP-22, one custom kind)

See [FEATURES_ROSTER.md](./FEATURES_ROSTER.md) for full details.

| Concept | Description | NIP |
|---------|-------------|-----|
| **Roster** | Structured post-event record of all participants with roles — wiki-style, open for community contributions | NIP-52, kind 31923 — the calendar event updated post-show |
| **Roster Confirmation** | Participant confirms their role on a roster (cryptographically signed) | NIP-32, kind 1985 — label event |
| **Roster Attestation** | Third-party vouch for a participant's role ("I was there, can confirm") | NIP-32, kind 1985 — label event |
| **Roster Contribution** | Community member adds a missing participant to a roster (wiki-style) | NIP-22, kind 1111 — comment scoped to the roster |
| **Setlist** | Per-artist song list for an event — songs linked to published tracks, featured artists tagged | Custom kind 32213 |

### Release Credit Events (Custom)

See [FEATURES_CREDITS.md](./FEATURES_CREDITS.md) for full details.

| Concept | Description | NIP |
|---------|-------------|-----|
| **Release Credits** | Full structured credits for a release — all participants with roles (performers, engineers, producers, label, visual, etc.) | Custom kind 32214 |
| **Track Credits** | Per-track credits that override/extend release-level credits (session musicians, featured artists, different songwriters) | Custom kind 32215 |
| **Edition** | Format-specific variant of a release — vinyl, CD, cassette, etc. with manufacturing details, catalog numbers, and edition-specific credits | Custom kind 32216; NIP-73 `i`/`k` tags for external IDs |

Confirmation, attestation, and contribution events are **shared with the roster system** — the same mechanisms (NIP-32 label events and NIP-22 comments), referencing different targets. This means the scene graph treats live and studio credits uniformly.

### Merchandise Events (NIP-15 + NIP-99)

See [FEATURES_MERCHANDISE.md](./FEATURES_MERCHANDISE.md) for full details.

| Concept | Description | NIP |
|---------|-------------|-----|
| **Stall** | A named product collection — artist merch store, record shop inventory, distro catalog. Includes currency and shipping zones. | NIP-15, kind 30017 |
| **Product** | A single item for sale — merch, physical music, accessories. Structured specs for size, format, condition, edition linking. | NIP-15, kind 30018 |
| **Resale Listing** | One-off fan-to-fan sale of merch or physical music. Same protocol as services marketplace. | NIP-99, kind 30402 |

The merchandise system requires **zero new custom event kinds** — it fully reuses NIP-15 and NIP-99 with Musiquay-specific conventions for specs and tags.

### Services Marketplace Events (NIP-99)

See [FEATURES_MARKETPLACE.md](./FEATURES_MARKETPLACE.md) for full details.

| Concept | Description | NIP |
|---------|-------------|-----|
| **Service Listing (Active)** | "Available for hire" or "Looking to hire" — structured with role, location, price, availability | NIP-99, kind 30402 |
| **Service Listing (Draft)** | Unpublished or closed listing | NIP-99, kind 30403 |

### Standard Nostr Events (Reused)

| Concept | Description | NIP |
|---------|-------------|-----|
| **Profile Metadata** | Display name, bio, avatar, banner | NIP-01 |
| **Follow / Contact List** | Who a user follows | NIP-02 |
| **Direct Messages** | Encrypted peer-to-peer messages | NIP-17 (NIP-04 legacy) |
| **Reactions** | Likes, emoji reactions | NIP-25 |
| **Reposts** | Sharing someone else's event | NIP-18 |
| **Deletion** | Requesting removal of own events | NIP-09 |

### Musiquay Kind Registry

Addressable kinds occupy the block 32210-32217. The regular (immutable) kinds are 3221, 3222, 32218, 32219, and 32220 - stored and counted, so they cannot be addressable, replaceable, or ephemeral. Re-checked free of collisions against the [registry of kinds](https://github.com/nostr-protocol/registry-of-kinds) as of 2026-09-28; register there before implementation.

| Kind | Name | Replaceability | Spec |
|------|------|----------------|------|
| 32210 | Track | Addressable | [FEATURES_MUSIC.md](./FEATURES_MUSIC.md) |
| 32211 | Album | Addressable | [FEATURES_MUSIC.md](./FEATURES_MUSIC.md) |
| 32212 | Playlist | Addressable | [FEATURES_MUSIC.md](./FEATURES_MUSIC.md) |
| 32213 | Setlist | Addressable | [FEATURES_ROSTER.md](./FEATURES_ROSTER.md) |
| 32214 | Release credits | Addressable | [FEATURES_CREDITS.md](./FEATURES_CREDITS.md) |
| 32215 | Track credits | Addressable | [FEATURES_CREDITS.md](./FEATURES_CREDITS.md) |
| 32216 | Edition | Addressable | [FEATURES_CREDITS.md](./FEATURES_CREDITS.md) |
| 32217 | Access filter | Addressable | [FEATURES_ACCESS.md](./FEATURES_ACCESS.md) |
| 3221 | Play report | Regular | [FEATURES_MUSIC.md](./FEATURES_MUSIC.md) |
| 3222 | Purchase order | Regular, NIP-59 only | [FEATURES_ACCESS.md](./FEATURES_ACCESS.md) |
| 32218 | Delivery receipt | Regular | [FEATURES_ACCESS.md](./FEATURES_ACCESS.md) |
| 32219 | Host aggregate | Regular | [FEATURES_ACCESS.md](./FEATURES_ACCESS.md) |
| 32220 | Publisher rollup | Regular | [FEATURES_ACCESS.md](./FEATURES_ACCESS.md) |

Access filters are blob-backed: the 32217 event carries filter parameters, the accepted payment legs (`mint` tags), and an `x` tag pointing at a Blossom blob holding the filter itself, so filters scale to any size while events stay small. An asset is **free if and only if no filter event exists for it**; free assets are served by open `GET` and still produce delivery receipts for listen counts. A requester identifies with a BUD-11 kind 24242 authorization token (`Authorization: Nostr <base64url>`), and the filter — not a payment token presented per request — is the entitlement.

NIP-reused event kinds (no custom kind): roster (NIP-52 kind 31923), confirmation and attestation (NIP-32 kind 1985), contribution (NIP-22 kind 1111), calendar (NIP-52 31922-31925), marketplace (NIP-15/NIP-99), live now-playing (NIP-38 kind 30315), private receipt delivery (NIP-59), payment requests (NUT-24/BUD-07), blind signatures (Cashu NUT-00 BDHKE).

**Message flows.** This registry says what each message type *is*; [PROTOCOL_FLOWS.md](./PROTOCOL_FLOWS.md) says how messages *move* — who sends what, in what order, over which transport (Nostr WebSocket, Blossom HTTP, Cashu mint HTTP, NIP-59 wraps), and what each side must verify first. It also carries the open decisions that must be settled before implementation, including the purchase-order message, blob-to-asset resolution, blind-signature verification, and ticket representation.

## Security Model

- **Identity:** Self-sovereign via Nostr keypairs. No passwords stored on servers. In the MVP, every user generates or provides their own keypair. Custodial key management (where the platform holds keys on behalf of users who sign up with email) is a future onboarding chapter.
- **Authorization:** Cryptographic signatures on all events. Relays verify signatures before accepting events.
- **Privacy:** Private playlists and direct messages use NIP-44 encryption (NIP-17 DMs, only readable by intended recipients).
- **Media access:** Not DRM-protected. Paid access is gated by signed membership filters ([FEATURES_ACCESS.md](./FEATURES_ACCESS.md)), not by encryption or copy protection. The security model is economic (make paying easy and transparent) rather than technical (make copying hard).
- **Payment security:** Lightning Network provides cryptographic payment guarantees. Custodial accounts are secured by the foundation's infrastructure.
- **Content policy:** Originals only. Enforcement mechanisms evolve post-MVP.

## Infrastructure

```
                         ┌──────────────┐
                         │    Scene     │
                         │  (Clients)   │
                         └──────┬───────┘
                                │ WebSocket
                         ┌──────▼───────┐
                         │   Musiquay   │
              ┌──────────┤    Relay     ├─────────┐
              │          └──────┬───────┘         │
              │                 │                 │
     ┌────────▼──┐  ┌──────────▼─────────┐  ┌─────▼─────────┐
     │  Blossom  │  │   Public Nostr     │  │  Lightning    │
     │  Server   │  │   Relays           │  │  Node         │
     │  (Media)  │  │   (Federation)     │  │  (Payments)   │
     └───────────┘  └────────────────────┘  └──────┬────────┘
                                                   │
                                             ┌─────▼─────┐
                                             │  Stripe   │
                                             │ (On-ramp) │
                                             └───────────┘
```

**The foundation operates:**
- The primary Musiquay relay
- Blossom server(s) for media hosting
- A Lightning node for custodial payment processing
- Stripe integration for fiat on-ramp
- The reference web client (MVP) and mobile clients (post-MVP)

**Independent operators can run:**
- Their own Nostr relays (festivals, labels, collectives)
- Their own blossom servers (artists, labels wanting full media control)
- Their own Lightning nodes (direct payments, zero platform dependency)

## Development Roadmap Context

The architecture is designed to be built incrementally, but the MVP ships as a full stack:

| Phase | Scope |
|-------|-------|
| **MVP** | Full stack: relay + blossom + Lightning + web client. Nostr-native identity only. Originals only. Core music features (publish, stream, pay). Basic scene profiles and social. |
| **Calendar pillar** | Location-based event calendar — NIP-52 calendar events, RSVPs, venue calendars, social discovery. See [FEATURES_CALENDAR.md](./FEATURES_CALENDAR.md). |
| **Roster pillar** | Event rosters with wiki-style editing, scene police validation, setlists, and live-to-recorded track linking. See [FEATURES_ROSTER.md](./FEATURES_ROSTER.md). |
| **Credits pillar** | Release credits — exhaustive structured credits for recorded music, format/edition tracking, shared validation model with rosters. Together with rosters, builds the complete scene graph. See [FEATURES_CREDITS.md](./FEATURES_CREDITS.md). |
| **Merchandise pillar** | Merch stores, record shop inventory, distro catalogs, fan resale — NIP-15 stalls/products and NIP-99 classifieds. Physical releases link to edition data. See [FEATURES_MERCHANDISE.md](./FEATURES_MERCHANDISE.md). |
| **Marketplace pillar** | Services marketplace — NIP-99 classified listings, structured service offerings and hiring needs, scene graph reputation. See [FEATURES_MARKETPLACE.md](./FEATURES_MARKETPLACE.md). |
| **Onboarding chapter** | Custodial identity management — managed keys behind email signup to lower the barrier for non-technical users. |
| **Moderation chapter** | Takedown processes, content policy enforcement, reporting mechanisms. |
| **Scene expansion** | Deeper professional networking — advanced credits, bookings, availability, waitlists, ticket pre-sales, release countdowns. |

Each phase builds on the protocol foundation laid in the MVP. The Nostr-native architecture means nothing is thrown away — custodial onboarding wraps the same keypair system, moderation adds policy layers on the same event model, the calendar, roster, credits, merchandise, and marketplace are just event kinds (NIP-52, NIP-15, NIP-99, and custom kinds) on the same relay, and every confirmed credit — live or studio — deepens the scene graph.