# Musiquay — Feature: Location-Based Event Calendar > Find cool shows and cultural events nearby, effortlessly. All highly social. ## Overview The event calendar is one of Musiquay's core platform pillars — alongside the scene graph and the services marketplace. It transforms Musiquay from a place where music lives into a place where the scene happens. Every city has a music scene. Every scene has shows, gigs, festivals, listening parties, workshops, art openings, film screenings. Right now, finding out what's happening requires following a dozen Instagram accounts, checking five different ticketing platforms, and hoping someone in your group chat saw the poster. It's fragmented, platform-locked, and hostile to discovery. Musiquay's calendar fixes this. Location-based. Social-first. Protocol-native. One place to find everything the scene is doing near you. ## Core Concepts ### Everything is a Nostr Event The calendar is not a separate system bolted onto the side. It is **Nostr events on the same relay**, using the same identities, the same social graph, the same protocol primitives as everything else in Musiquay. This means: - A venue publishing its weekly calendar is just a Nostr identity publishing calendar events. - A promoter creating a show listing is signing an event with their key. - A fan RSVPing is publishing a response event linked to the show. - A photographer sharing post-show photos is tagging the same event. - It all flows through the same feeds, the same discovery, the same social layer. ### NIP-52: Calendar Events Nostr already has a specification for calendar events — **NIP-52** — and it maps remarkably well to what Musiquay needs. Reuse first. **NIP-52 provides:** | Event Kind | Purpose | Musiquay Usage | |------------|---------|----------------| | **Kind 31922** | Date-based calendar events (all-day/multi-day) | Festivals, multi-day events, release dates | | **Kind 31923** | Time-based calendar events (specific start/end) | Shows, gigs, listening parties, workshops | | **Kind 31924** | Calendars (collections of events) | Venue calendars, promoter seasons, tour schedules | | **Kind 31925** | RSVPs | "I'm going", "Maybe", "Can't make it" | **Key NIP-52 features already built in:** - **Location** — free-text location field plus **geohash** (`g` tag) for searchable physical positioning. This is what powers geo-radius discovery. - **Participants** — `p` tags with pubkeys and roles. A show can tag the performing artists, the venue, the promoter, the sound engineer — anyone involved. - **Timestamps** — Unix timestamps with IANA timezone support for time-based events, ISO 8601 dates for date-based events. - **RSVPs** — Structured responses (`accepted`, `declined`, `tentative`) with availability indicators (`free`, `busy`). - **Hashtags** — `t` tags for categorization (genre, event type, etc.). - **References** — `r` tags for links to external resources (ticket pages, video calls, maps). - **Images** — Event artwork, posters, venue photos. The protocol already handles the hard parts. Musiquay's job is to build a great UI on top of it and extend where needed. ## Features ### Location-Based Discovery The primary interface: **what's happening near me?** - **Map view** — visual display of events on a map, filterable by date range, genre, event type, and distance. - **List view** — chronological list of upcoming events, sorted by proximity or date. - **Geo-radius search** — powered by NIP-52 geohash tags. "Show me everything within 20km this weekend." - **City/region browsing** — explore the scene in a specific city, even if you're not there yet. Planning a trip? See what's on. - **Venue pages** — each venue's Nostr profile aggregates all their upcoming events into a browsable calendar. Technical specs (capacity, PA, stage size) live on the profile. The calendar is just their published events. ### Social Calendar This isn't a cold listings page. It's **social by design**. - **"I'm going"** — RSVP to events (NIP-52 kind 31925). Your network sees your RSVPs in their feeds. - **See who's going** — before you decide, see which friends and people you follow are attending. "Oh, half my timeline is going to this — I should check it out." - **Share events** — repost event listings to your feed. Tag friends. "We should go to this." - **Post-event content** — after the show, photos, reactions, and reviews flow into the same event thread. The event becomes a living record of what happened, not just what was planned. - **Event roster** — the full, structured record of everyone who made the show happen, from the promoter to the bar staff. Wiki-style — the scene fills it in collaboratively. Plus setlists for every artist who performed. See [FEATURES_ROSTER.md](./FEATURES_ROSTER.md) for the complete roster system. - **Social discovery** — "Events popular with people you follow." The scene graph becomes a recommendation engine. ### Waitlists When a show sells out, it's not over. - **Join waitlist** — transparent, first-come-first-served queue. Your position is visible to you. - **Protocol-native** — waitlist positions are Nostr events. Fair, verifiable, no shady secondary market manipulation. - **Automatic notification** — when a spot opens, the next person in line gets notified. - **No scalping** — tickets and waitlist positions are tied to Nostr identities. The system is designed to resist the scalper economy by keeping everything identity-bound and transparent. **Protocol gaps to settle.** NIP-52 has no capacity field, so capacity is a Musiquay convention (`["capacity", ""]` on the event), and there is no authoritative queue head: promotion is a creator action (a DM to the attendee at the head of the recomputed queue), not a protocol transition. Queue order is derived from `joined_at` ascending, tie-broken by `d` ascending; the `position` tag is informational. The exact flow is specified in [PROTOCOL_FLOWS.md](./PROTOCOL_FLOWS.md). ### Ticket Pre-Sales Early access for the community. - **Supporter pre-sales** — artists can grant early ticket access to their followers, supporters, or people who've contributed above a threshold. - **Community pre-sales** — venues or promoters can offer early access to their local community or regulars. - **Lightning payments** — all ticket purchases flow through the same Lightning infrastructure. Instant settlement. No ticketing platform middleman taking 15% + fees. - **Tiered access** — configurable pre-sale windows. Day 1: artist supporters. Day 3: venue followers. Day 7: general availability. All expressed as Nostr event filters — "show this ticket event only to pubkeys in this follow list." **Access windows are access filters.** A pre-sale tier is a kind 32217 membership set — `d = presale::` — and the checkout checks the buyer against the current window's filter. Because relays serve all signed events to anyone, the window is enforced at purchase time, not by concealing the listing. **Ticket representation is an open decision.** Three options are laid out in [PROTOCOL_FLOWS.md](./PROTOCOL_FLOWS.md): a Cashu P2PK ticket (identity-bound, check-in burns the token at the mint, no double entry), a BDHKE blind-signed ticket (unlinkable but transferable and not identity-bound), or a NIP-59 wrapped venue-signed deed. It must be settled before the calendar pillar ships, because it is the only commerce flow with a fraud surface. ### Release Countdowns Building anticipation as a social experience. - **Artist announces a release** with a future date. A countdown event is published. - **Fans subscribe** — follow the countdown, get notified at drop. Like RSVPing to a release. - **Social anticipation** — see how many people are waiting. Watch the count grow. Organic hype. - **Drop notification** — when the release goes live, everyone subscribed gets it immediately through their WebSocket subscription. Real-time. - **Countdown as event** — the release moment can be paired with a listening party event, bridging the calendar and the music layer. ### Beyond Music The calendar isn't limited to gigs. The scene is broader than concerts. - **Art shows and exhibitions** — gallery openings, installations, visual art tied to the music world. - **Film screenings** — music documentaries, concert films, music video premieres. - **Listening parties** — communal first-listens, whether in a physical space or virtual. - **Workshops and masterclasses** — production workshops, sound engineering clinics, music business talks. - **Community gatherings** — meetups, scene hangs, record fairs, zine launches. - **Studio sessions** — open recording sessions, collaborative writing camps. If the scene cares about it, it belongs on the calendar. The `t` (hashtag) tags handle categorization without requiring a rigid taxonomy. ## Data Model ### Calendar Events (NIP-52 Reuse) The core data model is NIP-52 with Musiquay-specific conventions for tag usage. **Time-based event (kind 31923) — typical show listing:** ```json { "kind": 31923, "pubkey": "", "content": "Description of the event, lineup details, etc.", "tags": [ ["d", ""], ["title", "Friday Night at Lux Frágil"], ["summary", "DJ sets from local selectors"], ["image", "https://blossom.musiquay.com/"], ["start", "1735851600"], ["end", "1735876800"], ["D", "20090"], ["start_tzid", "Europe/Lisbon"], ["location", "Lux Frágil, Av. Infante Dom Henrique, Lisboa"], ["g", "eyckch"], ["p", "", "wss://relay.musiquay.com", "performer"], ["p", "", "wss://relay.musiquay.com", "performer"], ["p", "", "wss://relay.musiquay.com", "sound"], ["p", "", "wss://relay.musiquay.com", "photographer"], ["t", "electronic"], ["t", "dj"], ["price", "10", "EUR"], ["r", "https://tickets.example.com/event/123"] ] } ``` `D` is required by NIP-52 on time-based events: `floor(unix_seconds / 86400)`, repeated once per day the event covers. It is what makes date-window queries cheap without scanning `start`/`end`. **RSVP (kind 31925):** ```json { "kind": 31925, "pubkey": "", "content": "", "tags": [ ["a", "31923::", "wss://relay.musiquay.com"], ["d", ""], ["status", "accepted"], ["fb", "busy"] ] } ``` **Waitlist entry (kind 31925, tag convention):** ```json { "kind": 31925, "pubkey": "", "content": "", "tags": [ ["a", "31923::", "wss://relay.musiquay.com"], ["d", ""], ["status", "waitlist"], ["position", "14"], ["joined_at", "1735851600"] ] } ``` Queue order is derived from `joined_at` (tie-broken by `d` tag); `position` is informational — clients recompute it from the full set of waitlist RSVPs. ### Extended Events (Musiquay-Specific) Where NIP-52 doesn't cover Musiquay's needs, custom event kinds or tag conventions extend it. Following the reuse-first NIP strategy: | Concept | Approach | |---------|----------| | **Waitlist position** | Tag convention on NIP-52 RSVP (kind 31925) — `status` set to `waitlist`, plus `position` and `joined_at` tags. The RSVP's unique `d` tag and timestamp provide queue ordering. | | **Ticket purchase** | Cashu P2PK ticket or blind-signed ticket (open decision — see [PROTOCOL_FLOWS.md](./PROTOCOL_FLOWS.md)); settled by Lightning or Cashu with the payment linked to the calendar event via `a` tag | | **Release countdown** | Date-based calendar event (kind 31922) with a custom tag indicating it's a release drop | | **Pre-sale access** | Tag convention on ticket events — filtered by follow lists or supporter status | | **Post-event content** | Standard Nostr notes/media events that reference the calendar event via `a` or `e` tags | | **Event roster** | Full participant record with scene police validation — see [FEATURES_ROSTER.md](./FEATURES_ROSTER.md) | | **Setlists** | Per-artist song lists linked to tracks, with featured artist tagging — see [FEATURES_ROSTER.md](./FEATURES_ROSTER.md) | ## Integration with the Scene Graph The calendar doesn't exist in isolation. It is **deeply woven into the scene graph** documented in [ARCHITECTURE.md](./ARCHITECTURE.md). - **Venues** publish events → their calendar IS their Nostr event history of kind 31922/31923. - **Promoters** create events referencing venues and artists → the promoter-venue-artist relationship is explicit in the `p` tags. - **Artists** announce tour dates → a series of calendar events across venues, each tagging the artist. - **Crew** gets tagged on events → the sound engineer, photographer, and roadies who worked a show are part of the event record. - **Fans** RSVP and post content → social proof and post-event documentation enrich the scene graph. - **The roster** completes the picture → after the show, the full [event roster](./FEATURES_ROSTER.md) documents every participant with structured roles, scene police validation, and setlists. The roster is the permanent receipt for the event. A show is not just a listing. It's a node in the scene graph connecting venues, artists, crew, fans, service companies, and the content they create together. Before the show, it's a calendar event. After the show, it's a piece of the scene's permanent history. ## Discovery and Recommendations The social calendar enables organic discovery that cold listings cannot: - **"Popular with people you follow"** — events with high RSVP rates among your network surface naturally. - **Genre and role affinity** — if you follow post-punk bands, shows tagged `post-punk` rank higher. - **Venue affinity** — if you frequent a venue (past RSVPs), their new events surface prominently. - **Touring artists** — when an artist you follow announces a date in your city, it's highlighted. - **Scene momentum** — events gaining RSVPs quickly ("trending") can surface for broader discovery. No algorithm. No promoted listings. Just the social graph doing what social graphs do — connecting people to what their community cares about. ## Payments All financial transactions use the existing Lightning payment infrastructure: - **Ticket purchases** settle instantly via Lightning. No ticketing platform middleman. - **Stripe on-ramp** for listeners paying with credit cards — same custodial flow as music payments. - **Direct to venue/promoter** — sovereign venues and promoters with their own Lightning wallets receive payments directly. Zero platform cut. - **Pre-sale access** can be gated by supporter status (have they contributed above a threshold to this artist/venue?). Musiquay takes **zero cut** on ticket sales. The payment infrastructure is there to serve the scene, not to extract from it.