eventa — Functional Requirements

A multi-user event-planning app. Multiple people share one event, edit the same data, and see each other's changes in near-real-time. Android client + Python backend.

This document was distilled from a 6-round discussion with the codex CLI. The pivotal rounds:

Round 1 — brainstorm 13 features (web-app context).
Round 2 — critique + MVP-5.
Round 3 — initial tech sketch (web-app).
Round 4 — Android-only refinement (still single-user).
Round 5 — implementation plan.
Round 6 — multi-user trade-offs after the user decided collaboration is V1.

(Full transcripts in docs/.)

What "multi-user" means here

Each event has multiple members. One creator (owner), invited others (editors).
All members see the same shared state. When Alex marks "venue booked" done, Gerda sees it within seconds.
Anyone in the event can edit in V1. No viewer role, no per-field permissions.
Changes broadcast in real-time via WebSockets.
Offline editing is cut — you can read cached data offline; writing needs the network.
Identity is real — magic-link email login, multi-event support per user.

13 features

🎯 MVP — must ship for V1

1. Event Brief

Title, date(s), location, type, estimated guests, rough budget, "done means…" Edited by any event member, with optimistic concurrency (version stamp; conflicts surface as a "someone updated this — refresh?").

2. Guest List With RSVP State

Track guests, households, RSVP, dietary needs, lodging needs.

Android adds: Pick from device Contacts to import name/phone/email. Tap a guest to call/SMS/email — no typing.

3. Private Planning Checklist

Tasks with category, owner (event-member or free-text), due date. Includes packing/supplies as a category. Members see each other's checkmarks live.

4. Deadline Timeline (with notifications)

Chronological view of incomplete tasks: Overdue / This Week / This Month / Later. Server-side push notifications when: - a task you own has a deadline coming up (local trigger); - another member adds, completes, or assigns you a task.

5. Budget Buckets

Estimated vs actual costs per bucket. paid_by is a member reference or a free-text label.

Android adds: Camera-capture receipts and quotes; attach to the budget item; uploaded to backend (Postgres bytea or object storage).

📦 V1 expansion — ships after MVP

6. Household-Based Invitations

Group people into households so one outreach covers a couple/family. Outreach itself is still SMS/email handoff — eventa doesn't deliver invitations as the channel.

7. Personal Cost Ledger

Track who paid what and who owes whom across event members, since they're all real users now. Settlement summary still has to be acknowledged by people manually — no money movement.

Plan meals, drinks, portions, and grocery quantities derived from the guest list.

9. Guest Communication Log

Manual record of what was sent (save-the-date, invite, reminder…), plus quick send-SMS / send-email shortcuts.

10. Run of Show

Event-day schedule with times, owners, locations. Optional sync to device Calendar per user.

11. Post-Event Wrap-Up

Final costs, vendor feedback, what worked.

12. Venue / Vendor Contact Sheet

Addresses, phone, booking refs, deposits, cancellation terms. Tap-to-call / tap-to-navigate / tap-to-email.

13. Responsibility Assignment

Tasks / costs / run-of-show items have an owner. Owner can be a real event member (in which case they actually see it, since they're in the app) or a free-text label like "the caterer".

⚙️ V1 must-have infrastructure

Identity (auth)

Passwordless magic-link email. No passwords. No OAuth. The link takes the user back into the app and exchanges for a bearer token (~30-day TTL).

Invites

Email-based. Inviter clicks "invite Alex"; Alex gets an email with a one-click link; clicking it (a) creates Alex's account if needed and (b) joins them to the event as editor. Must feel like one flow, not three.

Real-time sync

WebSockets, per-event rooms. No polling.

Push notifications

FCM (Firebase Cloud Messaging). Server pushes when another member edits. The Android app translates the push into a refresh of the relevant view.

Backups / portability

Server-side pg_dump-able state. The user owns the data because they own the server.
GET /events/{id}/export.json per-event JSON export, available to any member.

🤖 What Android brings

Local reminders for personal deadlines (in addition to FCM-pushed events from other members).
Contacts integration for guest import.
Tap-to-act on guests/vendors (call, SMS, email, navigate).
Camera / file attachments for receipts and contracts.
Calendar export — deadlines + run-of-show land in the device calendar.

Cuts (deliberately not in scope)

❌ Decision Ledger — fold into Brief / Run-of-Show / Checklist.
❌ Packing & Supply Lists as a separate surface — Checklist category.
❌ Polling as a fallback for real-time. WebSockets only.
❌ Offline editing — read-cached, write-online. (Most of the value preserved with WS-on-resume + change feed.)
❌ Web client. Android only. Tiny static landing page exists for invite-acceptance UX, but no full web app.
❌ Viewer role / per-field permissions — owner + editor only.
❌ OAuth / passwords — magic-link only.
❌ OT / CRDT — last-write-wins with version stamping.
❌ User-facing audit timeline. Backend stores created_by / updated_by / change_log for fanout decisions; no UI for browsing.
❌ SMS as a channel. Email only.
❌ Notification preferences UI — one push class per event-change class; users mute via OS.

Hard non-goals

Not a SaaS aimed at the general public. Personal scale.
Not multi-tenant for the eventa operator either — one server, many events, all owned by their creators.
Not public RSVP links — RSVP is managed by event members.
Not a project-management tool.
Not a payment platform — paid_by refers to a member or a label.
Not a tablet / wear / TV variant in V1. Phone portrait first.