link a chant collection in event

[tenkus47]

1. Summary

Events can already link to a plan, accumulator, mantra, or timer. They cannot link to a group chant collection (group_recitation_collections). Add an optional FK so an event can point at a group’s curated chant list for practice during the event.

---

2. Motivation

Today	Gap
Event → plan_id, accumulator_id, mantra_id, timer_id	No link to group chant / recitation collection
Groups publish ordered chant collections	Events cannot surface that collection as the practice material
Studio can create events and collections separately	Authors cannot attach “use this chant book” to an event

Product need: for live or scheduled group events (e.g. group practice with a Meet link in the description), the event should reference the group chant collection participants should open.

Current state

Events

events.plan_id           → plans.id
events.accumulator_id    → accumulators.id
events.mantra_id         → mantra.id
events.timer_id          → timers.id
# no group_recitation_collection_id

CMS: POST/PUT /api/v1/cms/events
Public: GET /api/v1/events, GET /api/v1/events/{id}, GET /api/v1/events/today

Group chant collections

• Table: group_recitation_collections (soft delete via deleted_at).
• Owned by group_id → author_groups.id.
• CMS + public APIs already exist under author groups.

---

6. Proposal

6.1 Schema

Add to events:

Column	Type	Notes
group_recitation_collection_id	UUID NULL FK → group_recitation_collections.id ON DELETE SET NULL	Optional chant book for the event

Index: idx_events_group_recitation_collection_id.

6.2 API

Extend create/update/response models:

{
  "group_recitation_collection_id": "uuid | null"
}

• Create / update: optional field.
• List filters: ?group_recitation_collection_id= on CMS and public list endpoints.
• Response: include the id on EventDTO (omit when null, same as other optional links).

6.3 Validation

On set / change of group_recitation_collection_id:

1. Collection must exist and deleted_at IS NULL.
2. collection.group_id must equal event.group_id.
3. Otherwise → 400 (or 404 if not found — match existing FK link patterns in the codebase).

Clearing: allow explicit unlink (prefer supporting null on update so authors can remove the link).

6.4 Studio

On event create/edit: optional picker of the group’s chant collections. Show linked collection name on event detail when set.

Test plan

• Create event with valid same-group collection → persisted and returned.
• Create/update with collection from another group → rejected.
• Soft-deleted collection → rejected.
• Delete collection → event’s FK set to null; event remains.
• List filter by group_recitation_collection_id works on CMS + public.
• Update with null clears the link.
• Event without collection still works (field omitted).

---

9. Rollout

1. Migration + model/DTO/service/filter changes in Backend.
2. Studio: optional collection picker on event forms.