revents-online/MODULE_SPEC.md

rEvents — Event Aggregation & Parsing

Module ID: revents Domain: revents.online Framework: Next.js 14 / React 18 / Prisma 6 / PostgreSQL 16 Status: Active

Purpose

Aggregate events from external platforms (Luma, Meetup, iCal feeds) and parse unstructured text (emails, messages, flyers) into structured event data. Acts as the canonical event ingestion layer for the rStack, feeding normalized events to rCal, rInbox, and other modules.

Core Features

1. Source Aggregation — Connect Luma calendars, Meetup groups, and iCal/ICS feeds. Sync on demand (manual trigger or scheduled).
2. Text-to-Event Parsing — Paste unstructured text and extract structured event fields (title, date, location, cost, organizer, RSVP URL).
3. Unified Event Schema — All events normalized into a single schema with rich metadata (location, virtual/in-person, cost, category, tags).
4. rStack Integration — Events can be pushed to rCal via r_tool_source / r_tool_entity_id fields. Cross-module event references.
5. Space-scoped — Events and sources are scoped to spaces via subdomain routing ({space}.revents.online).

Data Model

Model	Description
User	Identity (DID from EncryptID)
EventSource	Connected platform (luma, meetup, ical, manual) with sync config
Event	Normalized event with full metadata, source tracking, rStack refs

Capabilities (Permission Model)

Capability	Min Role	Description
view_events	VIEWER	Browse and search events
create_event	PARTICIPANT	Create events manually or via parse
manage_sources	MODERATOR	Add/remove/sync event sources
configure_revents	ADMIN	Space settings, bulk operations

API Endpoints

Method	Path	Auth	Description
GET	/api/events	No	List/search events (filter by date, category, space, text)
POST	/api/events	Yes	Create event
GET	/api/events/:id	No	Get single event
PATCH	/api/events/:id	Yes	Update event
DELETE	/api/events/:id	Yes	Delete event
GET	/api/sources	Yes	List user's event sources
POST	/api/sources	Yes	Create event source
POST	/api/sources/:id/sync	Yes	Trigger sync for a source
POST	/api/parse	No	Parse unstructured text into event
GET	/api/health	No	Health check
GET	/api/me	No	Current user info

Source Adapters

Type	Config	Notes
luma	{ apiId } or { calendarUrl }	Lu.ma public calendar API
meetup	{ groupUrlName }	Meetup.com REST API (public groups)
ical	{ feedUrl }	Any .ics / iCal feed URL
manual	—	User-created events (auto-created per user)

Cross-Module Integration

• rCal: Events synced via r_tool_source: "revents" + r_tool_entity_id. rCal can query revents API for events by date range.
• rInbox: Event invitations arriving via email can be parsed and forwarded to revents for structured storage.
• rSpace Registry: Space activation creates DNS CNAME for {space}.revents.online.

Auth

EncryptID (WebAuthn + DID). JWT verified server-side via @encryptid/sdk. Public endpoints (event listing, parse) don't require auth. Write endpoints require valid EncryptID session.