Event Series Architecture

Event Series model durable continuity without weakening the independent identity of each Event. Use this page when changing Series or Edition contracts, persistence, relationships, reads, or integrity behavior. Use Event Series Frontend for page and authoring composition and Event Series Integrity for the manual operator reports.

Bounded Domain Model

The hierarchy has two explicit structures:

direct-events                    editions

Event Series                    Event Series
    |                               |
    +-- Event                       +-- Event Series Edition
    +-- Event                           |
                                        +-- Event
                                        +-- Event

A direct-events Series contains independently valid Events, such as tour stops or recurring club nights.
An editions Series contains first-class Editions, such as annual festival installments. Each Edition contains independently valid program Events.
A Series never mixes direct Events and Editions.
A Series cannot contain another Series, and an Edition cannot contain another Edition.
Category is independent from structure. festival, tour, recurring-program, and the other category codes describe editorial meaning rather than choosing the child shape.

This is intentionally not a generic tree, recurrence engine, or universal content graph.

Authority Matrix

Concern	Event Series	Event Series Edition	Event
Identity	Durable continuity across occurrences or Editions	One concrete installment	One independently valid occurrence
Editorial content	Series name, description, classification, continuity, and media	Edition name, description, broad location summary, disposition, and media	Event copy and media
Time	No schedule authority	Overall program window	Exact occurrence schedule
Physical location	No location authority	Official participating Venues	Exact attendance Venues
Digital attendance	No attendance identity	Purpose-typed virtual-attendance destinations	Event-specific digital destinations
Ticketing	Optional external Series portal	Edition passes or central external portal	Event-specific external destinations
Composition	Direct Events or Editions, according to structure	Program Events	Its own Artist, Venue, link, and ticket relationships
Revision	Series scalars and Series-owned relationships	Edition scalars and Edition-owned relationships	Event scalars, schedule, attendance, and Event relationships

Similar values at different levels are not duplicates when they make different claims. An Edition window describes the organizer’s overall program scope; Event schedules remain the detailed occurrence truth. Official Edition Venues are authored festival sites; Event Venues still say where each program item occurs.

Structure And Relationship Invariants

The database persists the structure discriminator and prevents incompatible children:

A structure transition is allowed only while the Series has no structure-dependent children.
An Edition belongs to exactly one Series.
Direct Event membership, Edition program membership, and Edition official-Venue membership are separate pair-unique many-to-many associations with their own surrogate row identities.
One Event may belong to multiple direct Series and multiple Editions. Membership does not establish a canonical Event parent.
Removing membership never deletes the related Event, Venue, Edition, or Series.
Soft-deleting a Series or Edition preserves descendants and relationship rows. Public traversal is suppressed through inactive ancestors without changing descendant lifecycle state.

Relationship writes resolve public target identities, require the capability-specific permission, lock the owning aggregate, and compare its expected revision. A meaningful write advances that owner once; an idempotent write preserves the revision. Series relationship changes do not advance Event or Edition revisions, and Edition relationship changes do not advance the parent Series or program Events.

Edition Program Windows

An Edition program window is either:

tba, with no bounds, precision, or reference zone; or
scheduled, with complete start and end bounds, one whole-window precision, and one IANA reference time zone.

Scheduled windows use inclusive calendar dates or precise date-time boundaries. Partial bounds and mixed precision are invalid. Date-time windows retain organizer-local values plus resolved exact projections; date-only windows remain calendar claims. The Edition window never overwrites or supplies an Event schedule.

Location And Attendance

Official Edition Venues are authored relationships, not a dynamic union of program Event Venues. This lets an organizer announce a multi-site Edition before its full program exists and keeps satellite or undeclared Event locations visible as reviewable discrepancies. An optional free-text location summary can communicate a city or district, but has no coordinate, filtering, or structured-location authority.

Edition attendance is derived from two sources:

At least one official Venue contributes physical attendance.
At least one virtual-attendance Edition link contributes digital attendance.

The resulting projection is in-person, digital, hybrid, or TBA. Information, registration, and ticket links do not imply digital attendance.

Links, Tickets, And Media

Series links are ordered identity-level destinations without an attendance purpose. Edition links are ordered and purpose-typed as information, registration, or virtual attendance. Series, Edition, and Event ticket destinations are external links only; Wavemap does not own prices, inventory, availability, fees, or checkout.

Series and Editions each own one profile image and an ordered gallery through entity-specific tables, routes, authorization, and read projections. They reuse the provider-neutral media storage and reconciliation kernel without entering a universal media table. Only ready media is public. Public contracts expose render-ready media DTOs and never storage locators or internal database IDs.

When an entity has no media, the shared Thumbnail Showcase renders one large primary placeholder and omits the secondary thumbnail row. Media-present pages render the profile image and gallery according to the same shared presentation contract.

Public Reads And Routes

The public route family is:

/[locale]/event-series
/[locale]/event-series/[eventSeriesID]
/[locale]/event-series/[eventSeriesID]/editions/[eventSeriesEditionID]

The Series Index is the discovery surface. There is no standalone Edition Index. A Series Details read contains either a bounded direct-Event preview or bounded Edition previews according to structure. Edition Details contains its bounded program, official Venues, links, ticket destinations, media, and derived attendance. Complete relationship-management and map reads remain separate protected or public capabilities rather than being inferred from bounded previews.

Public routes use public IDs and canonical slugs. Internal IDs stay server-side. Lifecycle-active Series and Editions are publicly eligible even when dates, attendance, Venues, or programs are still forthcoming; draft/public publishing remains reserved for the future CMS publishing contract.

Integrity Posture

Structural invalidity blocks persistence: unknown targets, inactive additions, incompatible structure children, duplicate pairs, or invalid program-window shapes fail before commit.

Cross-entity discrepancies do not block otherwise valid work. The system reports, but does not rewrite:

Program Events partly or wholly outside an Edition window.
Program Events using undeclared Venues.
Official Venues unused by the current program.
Program Event attendance outside the Edition’s derived attendance scope.

Finding identity is deterministic and includes public entity identity plus revisions. Reports are versioned, sanitized, read-only documents. They do not schedule, acknowledge, repair, or mutate records.

Migration And Reset Boundary

Ordinary migration preserves retained Series identity, editorial content, membership, links, ticket destinations, valid media, provenance, and revision. Known legacy vocabulary is classified into the current structure, category, and continuity codes. Ambiguous continuity or competing legacy/canonical profile claims fail closed with the previous authority intact.

Fresh schema application and retained migration are separate proof paths. A database reset is a distinct, destructive operation guarded to exact disposable development targets. Nothing in this architecture authorizes a reset in staging or production. Production rollout, rollback, repair, and cleanup require a separately approved operational plan.

Deliberate Deferrals

Recurrence rules, generation jobs, rolling materialization, and exceptions.
Recursive hierarchy or generic Event-to-Event containment.
Manual program ordering, stages, tracks, featured status, or Venue-within-program semantics.
Structured commerce, rich streaming-platform metadata, or a digital-Venue entity.
Secondary classifications and Edition-specific category overrides.
Relationship soft-delete/restore and Edition-specific audit history.
Automated integrity scheduling, acknowledgement, cleanup, or repair.
Event Series typeahead without a concrete selector or search consumer.
CMS draft/public publishing.