guestguard/docs/TIER2_PLAN.md

Tier 2 Production Plan

The next six months after launch. Features paying customers will ask for almost immediately — and that, if missing, will lose you the renewal.

Read CLAUDE.md for project conventions and docs/TIER1_PLAN.md for the launch-blocker work that must land before any block in this document. Tier 1 changes the auth model and notification infrastructure that several Tier 2 blocks depend on; do not start in parallel.

---

TL;DR

Eight work blocks (A–H), grouped into four waves that respect dependencies. Estimated effort: ~10–12 weeks for one engineer, ~6–7 weeks for two.

Wave 1 (quick wins, no model changes):
  A. Editable RSVPs ──┐
                      ├── (independent)
  B. Calendar integration ──┘

Wave 2 (authorisation surface widens):
  C. Multi-host / collaborators

Wave 3 (depends on Wave 2's role model):
  D. Event branding ──┐
  E. Host analytics ──┼── (parallelisable)
  G. Smarter fraud ───┘

Wave 4 (depends on Tier 1 notifications + Wave 3 stability):
  F. Reminders + broadcasts ──┐
                              ├── (parallelisable)
  H. Day-of check-in ─────────┘

---

Block A — Editable RSVPs

Why first: high-impact for guest UX, no schema-wide changes, no dependency on other blocks. Real wedding scenario: aunty said "attending" Monday and "can't make it" Friday — today she has no way to fix that.

Goal

A guest revisits their personal link after submitting and can change their response or plus-one count. History of changes is preserved so hosts aren't surprised by a silent overwrite.

Schema changes

Migration 0004_rsvp_edits.up.sql:

-- Track every prior state of an RSVP so hosts can see the trail.
CREATE TABLE rsvp_revisions (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  rsvp_id         UUID NOT NULL REFERENCES rsvps(id) ON DELETE CASCADE,
  prev_response   rsvp_response NOT NULL,
  prev_plus_ones  INT NOT NULL,
  prev_dietary    TEXT,
  changed_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_rsvp_revisions_rsvp ON rsvp_revisions(rsvp_id, changed_at DESC);

-- Allow up to 5 edits per guest; the limiter sits in Redis (Tier 1 Block C).
ALTER TABLE rsvps ADD COLUMN edit_count SMALLINT NOT NULL DEFAULT 0;

Backend

• PATCH /rsvp/{token} — new endpoint
  • Validates token (same as POST)
  • Re-runs the fraud check (different device on the edit attempt is itself a signal)
  • Snapshots current state into rsvp_revisions before applying
  • Rejects if edit_count >= 5 with HTTP 429
  • Increments edit_count
• GET /events/{id}/guests/{guest_id}/rsvp/history — host-only, returns current state plus all revisions
• Tokens stay valid after the first submission (today they get marked used in MarkUsed — remove that call from the submit handler)

Frontend

• /rsvp/{token} page detects existing RSVP from the access response
• Shows the current submission with a "Change my response" button
• Same form, prefilled with current values, hits PATCH on submit
• Confirmation page after edit: "Your response has been updated"
• Event detail page (host view): per-guest "Show history" toggle reveals the revision trail with timestamps

Tests

• Integration: submit → re-submit changes response and plus_ones → history table has one revision
• Integration: 6th edit attempt returns 429
• Integration: token used for editing isn't burned (can edit again next day)
• Unit: revision snapshot captures the previous state, not the new one

Definition of done

• Migration 0004_rsvp_edits.up.sql applied (with reversible down)
• Guests can edit their RSVP and see confirmation
• Hosts see edit history in the guest list
• Edit limit enforced (5)
• Existing single-submit flow still works for first-time RSVPs

Effort: ~3–4 days.

---

Block B — Calendar integration

Why first: trivial to build, instantly delights guests, demos extremely well to potential customers in sales calls. No dependencies, parallel with Block A.

Goal

After confirming attendance, guests can add the event to Google, Outlook, or Apple Calendar with one click.

Schema changes

None.

Backend

• GET /access/{token}/calendar.ics — returns a valid iCalendar file
  • Properties: SUMMARY (event name), DTSTART/DTEND (event date plus default 2-hour duration if no end specified), LOCATION (venue), DESCRIPTION (host's optional event description), UID (deterministic per event so re-downloads update the same calendar entry)
  • Content-Disposition: attachment; filename="event-name.ics"
• Helper in internal/calendar/ that builds the three add-to-provider URLs:
  • Google: https://www.google.com/calendar/render?action=TEMPLATE&text=...&dates=...&details=...&location=...
  • Outlook: https://outlook.live.com/calendar/0/deeplink/compose?...
  • Yahoo (bonus): https://calendar.yahoo.com/?v=60&title=...
• Embedded in the /access/{token} response so the frontend doesn't have to reconstruct them

Frontend

• Confirmation page (after successful RSVP): "Add to calendar" section with four buttons:
  • Google Calendar (opens link in new tab)
  • Outlook (opens link in new tab)
  • Apple Calendar (triggers .ics download)
  • "Other calendar app" (also .ics download)
• Same buttons on the RSVP page if the guest already responded

Tests

• Unit: .ics output is valid (parse it with github.com/arran4/golang-ical in the test or just regex the required fields)
• Unit: timezones encoded correctly (use TZID=UTC for simplicity, or derive from the host's locale — see open questions)
• Manual: import the generated .ics into Apple Calendar and Outlook, confirm it renders right

Definition of done

• .ics validates against RFC 5545 (no spec violations)
• All three provider links open with the right pre-filled event
• Test imports work in iOS Calendar, macOS Calendar, Outlook (web), Google Calendar
• Frontend buttons styled consistently with the rest of the confirmation page

Effort: ~1–2 days.

---

Block C — Multi-host / collaborators

Why before Wave 3: every later block (branding, analytics, fraud tuning, communications) needs to respect the role model. Build it once here, reference it everywhere after.

Goal

An event can have multiple hosts, each with one of three roles:

• Owner: full access, can delete the event, can manage collaborators
• Editor: can add/edit/remove guests, change event details, send messages, view analytics
• Viewer: read-only access to everything

Inviting a collaborator who doesn't yet have a GuestGuard account triggers a signup flow that lands them on the event after they verify.

Schema changes

Migration 0005_collaborators.up.sql:

CREATE TYPE collaborator_role AS ENUM ('owner', 'editor', 'viewer');

CREATE TABLE event_collaborators (
  event_id     UUID NOT NULL REFERENCES events(id) ON DELETE CASCADE,
  user_id      UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  role         collaborator_role NOT NULL,
  invited_by   UUID REFERENCES users(id),
  invited_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
  accepted_at  TIMESTAMPTZ,
  PRIMARY KEY (event_id, user_id)
);

CREATE INDEX idx_collaborators_user ON event_collaborators(user_id);

-- Pending invitations (invitee doesn't have an account yet, or hasn't accepted)
CREATE TABLE collaborator_invites (
  token_hash   TEXT PRIMARY KEY,
  event_id     UUID NOT NULL REFERENCES events(id) ON DELETE CASCADE,
  email        CITEXT NOT NULL,
  role         collaborator_role NOT NULL,
  invited_by   UUID NOT NULL REFERENCES users(id),
  expires_at   TIMESTAMPTZ NOT NULL,
  consumed_at  TIMESTAMPTZ,
  created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_collab_invites_event ON collaborator_invites(event_id) WHERE consumed_at IS NULL;

-- Backfill existing events: the current host_id becomes the owner.
INSERT INTO event_collaborators (event_id, user_id, role, accepted_at)
SELECT id, host_id, 'owner', created_at FROM events
ON CONFLICT DO NOTHING;

Decision: keep events.host_id as a denormalised "primary owner" pointer for query convenience, but treat event_collaborators as the source of truth for authz.

Backend

• New repo storage.CollaboratorRepo with: Add, List, UpdateRole, Remove, RoleFor(eventID, userID)
• New repo storage.InviteRepo for the invitation tokens
• Endpoints:
  • POST /events/{id}/collaborators — body { email, role }; creates an invitation; emits email via Tier 1's EmailSender
  • GET /events/{id}/collaborators — list current + pending
  • PATCH /events/{id}/collaborators/{user_id} — change role (owner-only)
  • DELETE /events/{id}/collaborators/{user_id} — remove (owner-only; refuses to remove the last owner)
  • POST /invites/{token}/accept — accept invitation; auto-creates user if none exists, redirects to signup if they need to set a password
• Update authz middleware: replace every WHERE host_id = userID check with a join through event_collaborators. Add a helper:
  • requireRole(eventID, userID, minRole) returns 404 if no membership, 403 if role is insufficient
  • Owner > Editor > Viewer (numeric internally for comparisons)
• Tighten existing endpoints:
  • PATCH/DELETE /events/{id} → owner only
  • POST/PATCH/DELETE on /guests, /tokens, /branding → editor+
  • All GET endpoints → viewer+

Frontend

• New "Team" tab on event detail page
• Shows current collaborators with avatars and roles
• "Invite" button opens a modal: email + role dropdown
• Pending invitations have a "Resend" + "Cancel" button
• Permission-aware UI everywhere:
  • Viewers don't see edit/delete buttons (server enforces too — UI is convenience)
  • Editors don't see the "Team" tab or "Delete event" button
• After accepting an invite, user lands on the event page

Tests

• Unit: role comparison helper
• Integration: invited editor can add guests; viewer gets 403 trying
• Integration: removing the last owner returns 400
• Integration: invite token is single-use and expires after 7 days
• Integration: existing single-host events still work (backfilled to owner)

Definition of done

• Migration 0005_collaborators.up.sql applied with backfill
• All three roles enforced server-side
• Invitation email arrives, accept link works for existing + new users
• Team tab functional for all role levels (with appropriate hiding)
• No regressions in single-host event flow
• useHost() / current user context exposes the role per event so the UI can branch

Effort: ~1.5–2 weeks.

---

Block D — Event branding

Why after multi-host: editors need permission to edit branding. The role check from Block C is the gate.

Goal

Hosts customise how their RSVP pages look — primary colour, logo, cover image, accent colour. Custom domains are an optional sub-block (see "Open questions").

Schema changes

Migration 0006_branding.up.sql:

CREATE TABLE event_branding (
  event_id        UUID PRIMARY KEY REFERENCES events(id) ON DELETE CASCADE,
  primary_color   TEXT,                  -- e.g. '#22c55e'
  accent_color    TEXT,
  logo_url        TEXT,
  cover_image_url TEXT,
  font_family     TEXT,                  -- one of a curated allowlist
  greeting_message TEXT,                 -- "Looking forward to seeing you!"
  updated_at      TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- Custom domain support (optional sub-block)
CREATE TABLE custom_domains (
  domain        TEXT PRIMARY KEY,
  event_id      UUID NOT NULL REFERENCES events(id) ON DELETE CASCADE,
  verified      BOOLEAN NOT NULL DEFAULT FALSE,
  verified_at   TIMESTAMPTZ,
  txt_challenge TEXT NOT NULL,           -- random nonce host adds as DNS TXT record
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

Backend

• File-upload service (internal/uploads/):
  • POST /uploads/image — multipart, accepts PNG/JPEG, max 2MB, scales/ re-encodes via github.com/disintegration/imaging for consistency
  • Stores in S3-compatible bucket (configurable via GG_S3_* env vars; use local MinIO container for dev)
  • Returns the public CDN URL
• PUT /events/{id}/branding — upsert branding row (editor+)
• GET /events/{id}/branding — read (any role)
• GET /access/{token} — include the event's branding in the response so the RSVP page can render with it
• Colour validation: must be valid hex; logos/covers must be from our own CDN domain (don't allow arbitrary URLs — XSS surface)
• Custom domain sub-block (optional, can defer):
  • POST /events/{id}/custom-domain — register, returns TXT challenge
  • POST /events/{id}/custom-domain/verify — checks DNS, marks verified
  • Server-side: dynamic ingress route that resolves a domain to its event_id and serves the RSVP page (this is heavy; needs Traefik / ingress config — likely a k8s task, not pure Claude scope)

Frontend

• "Branding" tab on event page (editor+)
• Colour pickers (use @vueform/colorpicker or HTML5 input)
• Logo upload + preview, cover image upload + preview
• Font picker (curated list: Inter, Playfair Display, Cormorant, etc. — keeps load times sane)
• Live preview pane on the right (re-uses the invitation card mockup component we already built — pass branding props)
• RSVP page reads branding from /access response, applies via CSS vars

Tests

• Unit: hex colour validation, image size/format validation
• Integration: upload → URL returned → branding row links it
• Integration: RSVP page renders with custom colours

Definition of done

• Logo + colours customisable and preserved
• RSVP page reflects branding on load (no flash of default colours)
• Image upload caps enforced server-side
• Invitation emails (from Tier 1 Block D) also honour branding
• Custom domain sub-block: decision made (ship or defer to Tier 3)

Effort: ~1 week without custom domain, ~1.5 weeks with.

---

Block E — Host analytics

Why now: hosts have enough data once events have been running for a week. Pure read-side feature, no schema changes, parallel-safe with D and G.

Goal

A polished "Analytics" tab per event showing the numbers hosts actually care about: response rate over time, who hasn't opened their invitation, time-to-respond, plus-one breakdown.

Schema changes

None directly. To support source/channel attribution later, add a utm_source column to tokens or guests (cheap and useful):

ALTER TABLE tokens ADD COLUMN utm_source TEXT;

(Set when the host issues the token via a labelled link.)

Backend

• GET /events/{id}/analytics (any role) — returns:
  • Overview: total invited, confirmed, declined, maybe, no-response
  • Response rate: daily counts of new responses since invitation went out
  • Funnel: invited → opened (at least one access_log) → responded
  • Time-to-respond histogram: buckets of 0–1h, 1–24h, 1–3d, 3–7d, 7d+
  • Plus-one distribution: count of RSVPs with 0, 1, 2, 3+ plus-ones
  • Channel attribution: response counts grouped by utm_source if set
  • Stale guests: list of guests who haven't opened their link, sorted by oldest invitation first
• All counts derived from existing tables via aggregation queries; cache in Redis with 60-second TTL since the same dashboard is hit repeatedly
• GET /events/{id}/analytics/export.csv — flat export of the guest list with response, time-to-respond, plus-ones, and source columns

Frontend

• "Analytics" tab on event page
• Charts via chart.js + vue-chartjs:
  • Line chart for response rate over time
  • Donut for response breakdown
  • Bar chart for time-to-respond histogram
• Stale-guests table with a "Send a reminder" button (links into Block F when that ships; until then, just a "Copy link" affordance)
• CSV export button

Tests

• Unit: aggregation logic on synthetic data (matches expected counts)
• Integration: analytics endpoint returns sensible numbers on a seeded event
• Integration: cache invalidation on new RSVP (or accept up-to-60s staleness)

Definition of done

• Five charts rendering with real data
• CSV export works in Excel + Numbers
• Stale guests list correct
• Cache layer reduces DB load (verified via logs / Postgres pg_stat_statements)

Effort: ~1 week.

---

Block F — Reminders + broadcasts

Why late: depends on Tier 1 Block D (notifications) being rock-solid. Sending the wrong reminder to 200 wedding guests is a reputational incident. Also depends on Block C so editors can compose broadcasts without elevated permission.

Goal

• Auto-reminders: 7 days before, 1 day before, day-of (configurable on/off per event)
• "Last call": 3-day pre-event nudge to guests who still haven't responded
• Custom broadcasts: host writes a message, picks an audience (all / attending / pending / declined / maybe), sends now or schedules

Schema changes

Migration 0007_messages.up.sql:

CREATE TYPE message_audience AS ENUM ('all', 'attending', 'pending', 'declined', 'maybe');
CREATE TYPE message_channel AS ENUM ('email', 'sms', 'both');
CREATE TYPE message_status AS ENUM ('draft', 'scheduled', 'sending', 'sent', 'cancelled', 'failed');

CREATE TABLE scheduled_messages (
  id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  event_id     UUID NOT NULL REFERENCES events(id) ON DELETE CASCADE,
  send_at      TIMESTAMPTZ NOT NULL,
  audience     message_audience NOT NULL,
  channel      message_channel NOT NULL,
  template_key TEXT,                     -- 'reminder_7d' | 'last_call' | NULL for custom
  subject      TEXT,
  body         TEXT NOT NULL,
  status       message_status NOT NULL DEFAULT 'draft',
  sent_at      TIMESTAMPTZ,
  recipient_count INT,
  created_by   UUID REFERENCES users(id),
  created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_messages_due ON scheduled_messages(send_at)
  WHERE status = 'scheduled';

-- Track per-recipient delivery so a single failed send doesn't fail the batch
CREATE TABLE message_deliveries (
  message_id   UUID NOT NULL REFERENCES scheduled_messages(id) ON DELETE CASCADE,
  guest_id     UUID NOT NULL REFERENCES guests(id) ON DELETE CASCADE,
  status       TEXT NOT NULL,            -- 'pending' | 'sent' | 'bounced' | 'skipped'
  sent_at      TIMESTAMPTZ,
  error        TEXT,
  PRIMARY KEY (message_id, guest_id)
);

Backend

• New repo storage.MessageRepo
• Endpoints (editor+):
  • POST /events/{id}/messages — create scheduled or send-now message
  • GET /events/{id}/messages — list
  • PATCH /events/{id}/messages/{message_id} — edit (only while scheduled)
  • POST /events/{id}/messages/{message_id}/send-now — promote scheduled → sending
  • DELETE /events/{id}/messages/{message_id} — cancel
• Scheduler worker (extend cmd/notifier):
  • Polls scheduled_messages WHERE status = 'scheduled' AND send_at <= now() every 30s
  • Picks one, marks sending, fans out to recipients filtered by audience
  • Uses existing notification infra (Twilio + SES from Tier 1 Block D)
  • Per-recipient row in message_deliveries; failures recorded, not retried (keep failures visible to host)
  • Marks parent sent when all deliveries complete
• Auto-reminder seeding: on event creation (or when first guest added), insert scheduled_messages rows for reminder_7d, reminder_1d, last_call (3d, pending audience). Host can edit or cancel before they fire. Skip if event date is too close.
• Template variables: {{guest_name}}, {{event_name}}, {{event_date}}, {{venue}}, {{rsvp_link}} — rendered server-side per recipient

Frontend

• "Communications" tab on event page (editor+)
• "Compose new message" form with:
  • Audience selector (all / attending / pending / etc.) with live recipient count
  • Channel selector (email / SMS / both — SMS gated by Pro tier)
  • Subject + body fields with variable insertion buttons
  • Preview pane that renders one recipient as an example
  • "Send now" or "Schedule for…" datetime picker
• Tabs within the section: Scheduled · Sent · Drafts
• Sent list shows delivery counts (200 of 203 delivered) with per-row drill-down
• Click on a scheduled auto-reminder to edit or disable

Tests

• Integration: scheduled message fires within 1 minute of send_at
• Integration: audience filter correctly excludes guests
• Integration: cancelled message doesn't send
• Integration: variable substitution renders correctly
• Unit: scheduler skips events whose date is in the past

Definition of done

• Auto-reminders fire correctly on a seeded event
• Custom broadcasts deliverable to filtered audience
• Recipient count accurate before send
• Per-recipient delivery status visible to host
• SMS billing meter increments correctly (Tier 1 Block F usage counter)
• Unsubscribe header respected (don't email opted-out addresses)

Effort: ~1.5–2 weeks.

---

Block G — Smarter fraud detection

Why now, not Tier 1: the current scorer works well enough for launch (it catches forwarded links). Hosts at scale will start asking "why was my aunty flagged?" — and we'll need the tools in this block to answer.

Goal

Reduce false positives we already know about (the consecutive 0 → 61 scoring artefact), let hosts tune thresholds for their event, and start collecting labelled data for a future ML model.

Schema changes

Migration 0008_fraud_v2.up.sql:

ALTER TABLE access_logs
  ADD COLUMN geo_country TEXT,
  ADD COLUMN geo_city    TEXT,
  ADD COLUMN geo_lat     DOUBLE PRECISION,
  ADD COLUMN geo_lon     DOUBLE PRECISION;

ALTER TABLE events
  ADD COLUMN fraud_medium_threshold SMALLINT NOT NULL DEFAULT 30,
  ADD COLUMN fraud_high_threshold   SMALLINT NOT NULL DEFAULT 60,
  ADD COLUMN fraud_block_threshold  SMALLINT NOT NULL DEFAULT 85;

CREATE TABLE fraud_feedback (
  access_log_id UUID PRIMARY KEY REFERENCES access_logs(id) ON DELETE CASCADE,
  verdict       TEXT NOT NULL CHECK (verdict IN ('legitimate', 'suspicious')),
  marked_by     UUID REFERENCES users(id),
  note          TEXT,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE event_allowlists (
  event_id   UUID NOT NULL REFERENCES events(id) ON DELETE CASCADE,
  ip_cidr    INET NOT NULL,
  label      TEXT,                       -- e.g. "Office network"
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (event_id, ip_cidr)
);

CREATE INDEX idx_allowlists_event ON event_allowlists(event_id);

Backend

• Geolocation in the fraud engine (fraud-engine/app/geo.py):
  • Integrate MaxMind GeoIP2 (lite is free, paid is more accurate) or a cheap API like ipapi.com
  • Cache lookups in Redis (TTL 30 days, geolocation rarely changes)
  • New scoring feature geo_jump: large distance between consecutive accesses for the same guest (> 500 km in < 1 hour ⇒ suspicious)
• Per-event thresholds: the gRPC ScoreInput already carries EventID; load the event's thresholds at scoring time, cache for 60s in the engine. Apply thresholds to the band assignment instead of the hardcoded 30/60/85 constants in scoring.py.
• Allowlist short-circuit: if the request IP matches any event_allowlists.ip_cidr for the event, score = 0, band = low. Implemented in the API before calling the fraud engine.
• Feedback endpoint:
  • POST /events/{id}/access-logs/{log_id}/feedback (editor+)
  • Body: { verdict: "legitimate" | "suspicious", note?: string }
  • Writes to fraud_feedback
• Allowlist management (editor+):
  • GET/POST/DELETE /events/{id}/allowlist
• Tightening the consecutive 0 → 61 false-positive: change scoring.py to require two signals (not just fingerprint_mismatch) to cross into high. Tune weights based on early production data.

Frontend

• New "Security" tab on event page (editor+)
• Threshold sliders with live preview ("With these settings, 12 of your current 47 access events would be flagged")
• Allowlist table with add/remove
• In the existing live monitor: each Suspicious or Blocked entry gets a small dropdown:
  • "Mark as legitimate" (sends feedback, hides the pill, updates band)
  • "Confirm suspicious" (acknowledged, helps train future model)
• Optional: a "Why was this flagged?" tooltip on each entry showing the contributing reasons (we already have reasons in access_logs)

ML model (later, not in this block)

The data captured in fraud_feedback is what a real classifier will train on. This block is infrastructure for the model, not the model itself. Once you have ~500 labelled rows, train a scikit-learn LogisticRegression or GradientBoostingClassifier, ship it as a second path in scoring.py with a feature flag.

Tests

• Unit: geo-distance calc, allowlist CIDR match, threshold band assignment
• Integration: feedback recorded, allowlist bypass works
• Integration: per-event threshold overrides default
• Manual: verify MaxMind lookup returns sensible country for known IPs

Definition of done

• Geolocation enriched on every scored access
• Per-event thresholds respected
• Allowlists bypass scoring (covers corporate offices, family Wi-Fi)
• Feedback recorded; UI lets hosts mark legitimate/suspicious
• The known consecutive-scoring false positive is reduced (measured against current data)

Effort: ~2 weeks.

---

Block H — Day-of check-in

Why last: most complex block, depends on a stable platform. This is the killer demo feature that wins enterprise + wedding-planner contracts.

Goal

A host (or designated check-in volunteer) opens a PWA on their phone at the venue, scans the QR code on each confirmed guest's invitation, and the dashboard updates with a live arrival count. Works offline (with queued sync) since venue Wi-Fi is unreliable.

Schema changes

Migration 0009_checkin.up.sql:

CREATE TABLE check_ins (
  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  guest_id        UUID NOT NULL REFERENCES guests(id) ON DELETE CASCADE,
  checked_in_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
  checked_in_by   UUID REFERENCES users(id),
  arrival_count   INT NOT NULL DEFAULT 1,    -- guest + plus-ones who showed up
  notes           TEXT,
  walk_in         BOOLEAN NOT NULL DEFAULT FALSE
);

CREATE UNIQUE INDEX idx_checkins_guest ON check_ins(guest_id);
CREATE INDEX idx_checkins_event ON check_ins(guest_id, checked_in_at);

-- The check-in payload is a signed JWT in the QR code, not a database row,
-- so no new column on `guests` needed.

Backend

• QR code generation:
  • In the RSVP confirmation flow, generate a JWT signed with a per-event HMAC secret containing { event_id, guest_id, exp } (exp = event date + 24h)
  • Encode as a QR PNG via github.com/skip2/go-qrcode
  • Embed in the confirmation email and on the confirmation page so guests can show it at the door (printed or on phone)
• POST /events/{id}/check-in (editor+):
  • Body: { qr_payload: "...", arrival_count: 2 }
  • Validates the JWT (signature, expiry, event match)
  • Inserts a check_ins row (UNIQUE prevents duplicate check-in)
  • Returns guest details for the scanner UI to confirm
  • Broadcasts check_in.recorded to the WS hub
• GET /events/{id}/check-ins — live list
• POST /events/{id}/walk-ins — register a walk-in (creates guest + check_in in one transaction)
• New WS event type check_in.recorded for the live monitor + a dedicated arrivals counter widget

Frontend (PWA)

• New page /dashboard/events/{id}/scanner (editor+)
• PWA manifest + service worker so it installs to the home screen and works without a live connection
• Camera via getUserMedia + QR decoding via jsQR (or zxing-wasm for better accuracy in low light)
• After successful scan:
  • Show the guest's name + expected plus-ones large on screen
  • "X people in your party — confirm" buttons (1, 2, 3, or "Other" → input)
  • Tap → POST to /check-in → green success, vibrate, beep
  • Already-checked-in → orange warning, doesn't double-record
• Offline queue: failed POSTs go into IndexedDB, retried with exponential backoff when online again. Show a small "3 scans queued" badge
• Walk-in form: button on scanner → modal with name + plus-ones → creates guest + check-in in one tap
• Live arrivals dashboard widget (on main event page): big number "47 of 85 arrived" with a thin chart of arrival rate over the last hour. Updates via WS in real time.

Tests

• Unit: JWT generation + verification with replay protection
• Integration: scan → check-in recorded → arrival count increments
• Integration: duplicate scan returns 409 with friendly message
• Integration: walk-in creates both guest and check-in in one transaction
• E2E (manual): scanner works on iOS Safari and Android Chrome with real printed QR codes; offline scan syncs when network returns

Definition of done

• Confirmation page + email include a scannable QR code
• Scanner PWA installs and works on iOS Safari + Android Chrome
• Live arrivals counter updates on the dashboard within 2 seconds
• Walk-in flow tested end-to-end
• Offline scanning queues and recovers gracefully
• Plus-one verification at the door records the actual party size
• Already-checked-in case handled (no duplicates, clear feedback)

Effort: ~2–2.5 weeks.

---

Cross-cutting concerns

Audit logging

Every collaborator change, branding change, message send, threshold tweak, allowlist edit, and check-in is logged with userID, action, target_id, request_id. Reuse the audit logging baseline from Tier 1.

Tier-gating

Several Tier 2 features should be limited by subscription tier (Tier 1 Block F):

• Free: no SMS reminders, no custom domain, max 1 collaborator (viewer only), no analytics export
• Personal: SMS reminders capped at 100/month, 1 editor + unlimited viewers, analytics export
• Pro: 1,000 SMS/month, unlimited collaborators, all branding, custom domain
• Business: unlimited SMS, multi-event, white-label branding

Enforcement lives in the middleware introduced by Tier 1 Block F's requireTier(...) helper.

Feature flags

Each of A through H lands behind a feature flag (features.editable_rsvp, features.checkin_pwa, etc.). Roll out to staging → beta customers → everyone over a week or two. Flag values stored in a feature_flags table or as env vars on the API container.

Migration discipline

• Every migration has a tested *.down.sql
• Backfills (like event_collaborators from events.host_id) are idempotent so re-running is safe
• No destructive operations without backup verification first

---

Open questions

Resolve early — some have material effort implications:

1. Custom domain support — Tier 2 or Tier 3?

   • The application code is straightforward. The hard parts are dynamic ingress configuration, automated cert provisioning (LetsEncrypt), and DNS-challenge automation — all infra work. Recommend defer to Tier 3 unless you have a customer asking for it.

2. Calendar timezone handling — UTC or host's locale?

   • UTC works correctly everywhere but looks weird ("dinner at 17:00 UTC"). Local timezone is friendlier but adds complexity. Recommend: store event_date as TIMESTAMPTZ (already done), display in browser locale, emit .ics with explicit TZID= derived from the host's profile.

3. SMS reminders — opt-in by default or off?

   • SMS deliverability is fragile and costs real money. Recommend: opt-in per event in the "Communications" tab, with a usage warning that references the tier limit.

4. QR check-in: pre-printed badge support?

   • Some weddings hand out badges with names + QR. Same QR mechanism would work — host downloads a print-ready PDF of all QR codes for the attending list. Defer to Tier 4 (marketplace integrations).

5. Multi-host invitation expiry

   • 7 days proposed in Block C. Should the invitation be reusable in case the recipient deletes the email? Probably no — resend instead. Decided.

6. Branding: can guests see the host's personal logo, or only the event's?

   • Recommend event-only. Hosts may not want personal branding on a wedding RSVP page.

7. Analytics: do we expose access_log details to viewers?

   • Includes IP addresses. Recommend: viewers see aggregates only; editors+ see the individual log entries.

---

Sequencing summary table

Wave	Block	Depends on	Effort (1 eng)	Parallel with
1	A. Editable RSVPs	—	4d	B
1	B. Calendar integration	—	2d	A
2	C. Multi-host	A, B done	1.5–2w	—
3	D. Event branding	C	1w (1.5w w/ custom domain)	E, G
3	E. Host analytics	C	1w	D, G
3	G. Smarter fraud	C	2w	D, E
4	F. Reminders + broadcasts	Tier 1 D + C	2w	H
4	H. Day-of check-in	C, F (for QR-in-reminders)	2.5w	F

One engineer, sequential: ~11 weeks. Two engineers, parallel-where-possible: ~6.5 weeks.

---

What's not in Tier 2 (deliberate)

These are tempting but belong in Tier 3 or 4:

• Observability (Prometheus, OpenTelemetry tracing, Sentry) — Tier 3
• Native iOS/Android apps — PWA from Block H is enough for v1; native is Tier 3
• i18n — Tier 3 (translated templates touch every notification template)
• SSO (SAML/OIDC) — Tier 4
• Public API + webhooks — Tier 4
• CRM sync (Salesforce, HubSpot) — Tier 4
• Zapier integration — Tier 4
• AI setup assistant — Tier 4
• Marketplace integrations (caterers, photographers) — Tier 4
• Biometric / face check-in — Tier 4

Ship Tier 2 first. The story by the end of it: "personal invitations, shared with your team, branded for your event, with reminders, real arrival tracking, and security that adapts to your venue". That's a genuinely differentiated product.