Skip to content

Latest commit

 

History

History
450 lines (393 loc) · 80.2 KB

implementation.md

File metadata and controls

450 lines (393 loc) · 80.2 KB

Implementation

Entry Points

Sandbox checkout confirmations use lib/devcon26-test-checkout-email-delivery.ts for fail-closed configuration and TEST content, lib/supabase/devcon26-test-checkout-emails.ts for typed outbox RPCs, and server/devcon26-test-checkout-email-delivery.ts for frozen-payload delivery. The sandbox route module registers the shared-secret-protected internal retry endpoint. Worker slot 12 of each 15-minute cycle claims at most five emails; payment verify/webhook requests never call Resend synchronously. See the finance feature document for activation boundaries.

File Role
src/main.ts Vue app bootstrap — waits for initial router readiness, then selects the public or organizer root before mounting Vue Router, TanStack Query, global CSS, and delegated button press feedback
src/App.vue Protected organizer app shell and top navigation, including the organizer-access boot surface
src/PublicApp.vue Public-only app shell with no organizer header, navigation, or session bootstrap
lib/app-boot.ts Shared route-aware first-paint markup and styles injected into the Vite build shell and Hono development fallback
src/admin-routes.ts Configurable organizer route base path helpers
src/organizer-viewport.ts Shared phone/tablet organizer route policy and breakpoint helpers
src/components/OrganizerPhoneShell.vue Shared phone header, capability-filtered conference destinations, bottom navigation, and organizer More menu; existing route keys and session locks stay in the app shell
src/components/MobileSectionPicker.vue / src/composables/usePhoneSectionFit.ts Shared dropdown for long or overflowing phone subsection rows, with resize cleanup and fit measurement for short tabs
src/speaker-intake-route.ts Testable public route record for generated private speaker links
src/router.ts Active Vue route table; page components are lazy-loaded per route so the initial app bundle does not include every public and organizer view
lib/email/previews.ts Owner email-preview catalog that maps every active scenario to the existing production renderer using safe sample fixtures
src/components/ui/AppToaster.vue Globally mounted app-themed Sonner toaster
src/components/ui/BoneyardPageSkeleton.vue Responsive Boneyard loading states generated from isolated, synthetic page fixtures
src/lib/query.ts Shared TanStack Query client defaults for client-side API caching and invalidation
src/lib/api.ts Shared browser fetch helpers, query keys, and common API response types
src/lib/notify.ts Typed notification helper that targets the app toaster
src/views/DashboardView.vue DEV::CON[] landing page backed by current mock data
src/views/ArchiveView.vue / ArchiveEventView.vue Public event archive and published item surfaces
src/views/CfpView.vue / SpeakerTalkIntakeView.vue CFP and private selected-proposal/manual Archive Request flows; the CFP receipt is image-led and responsive after a public proposal is received.
src/views/FeedbackView.vue Public event feedback form for active or auto-open campaigns
lib/event-feedback-report.ts Pure event-feedback aggregate model used by the organizer dashboard
lib/speaker-archive-email.ts Eligible program-item selection and strict stored speaker-email resolution
lib/email/scenarios.ts / lib/email/resend.ts / lib/email/templates/monthly-archive-request.ts Code-owned sender and subject policy, Worker-native Resend client, and Archive Request email
lib/email/public-email-preflight.ts Shared public-form email syntax, provider-typo, disposable-domain, DNS fallback, domain-only cache, and fail-open resolver policy
src/components/NaviiAvatar.vue Local deterministic Navii avatar renderer for System Design participants
src/views/NotFoundView.vue Branded fallback for unknown Vue routes
src/views/admin/* Active admin event/talk/speaker/System Design management views
lib/luma-attendance.ts Luma guest CSV normalization and organizer attendance metrics
server/quiz-state.ts Quiz state read model and explicit phase-advance command helper
lib/supabase/browser.ts / server.ts Typed Supabase clients for browser-safe anon access and server-only service-role access
lib/supabase/community-events.ts Supabase-backed community event repository and public meetup DTO mapper
lib/supabase/media.ts Server-side Supabase Storage upload helper for meetup covers and selected event photos
supabase/migrations/* Supabase SQL migrations, starting with tester feedback tables
server/app.ts Hono composition root — app-wide middleware, feature route registration, remaining legacy API handlers, and dev SPA fallback
server/routes/annual-conference-speakers.ts Complete nine-route Annual Conference speaker HTTP registrar
server/routes/annual-conference-speakers/schemas.ts Proposal, decision, deadline, and logistics Zod transport contracts
server/routes/annual-conference-speakers/delivery.ts Acceptance-email delivery and persisted provider status
server/annual-conference-request.ts Request-scoped Annual Conference edition, service, finance, and capability composition
server/http/* Shared Hono bindings, public-intake protection, safe errors/origin resolution, and speaker mutation coordination
server/index.ts Bun production server — serves dist/ and /api/* on one port
vite.config.ts Vite + Vue + Hono dev-server wiring
data/seed.ts Seed script — run via pnpm seed
tools/scenario-atlas/server.ts Loopback-only Atlas server and narrow local JSON API; never imported by production entrypoints
tools/scenario-atlas/catalog/workflows.json Tracked workflow, checkpoint, scenario, expectation, and completeness contracts

Route-to-Module Notes (Current)

  • Annual Conference speaker HTTP boundary

    • server/routes/annual-conference-speakers.ts registers the public CFP, organizer review, acceptance/retry, and private logistics workspace endpoints without changing their paths or response contracts.
    • Transport schemas and acceptance delivery live beside the registrar; database proposal isolation and hash-only token operations remain in lib/annual-conference-speakers.ts.
    • server/annual-conference-request.ts centralizes request-scoped edition lookup and capability/service composition used by both extracted and remaining conference routes.
    • server/http/public-intake-protection.ts centralizes public client identity, atomic rate-limit responses, email preflight, and Turnstile validation. Global public/protected path classification remains in server/app.ts so middleware order is unchanged.
    • server/annual-conference-speaker-routes.test.ts protects exact one-time route registration; the full proposal and security route suites remain the behavioral characterization boundary.
  • Event + CFP flow

    • Active Vue pages: src/views/CfpView.vue, src/views/EventRegistrationView.vue, src/views/admin/AdminEventsView.vue, src/views/admin/AdminEventView.vue, src/views/admin/AdminRegistrationsView.vue, and src/views/admin/AdminRegistrationDisplayView.vue
    • Public CFP page: app/(public)/cfp/[eventId]/page.tsx
    • APIs: /api/events/[eventId], /api/events/[eventId]/checklist, /api/events/[eventId]/speaker-submissions, /api/events/[eventId]/registrations, /api/registration/events/[eventId], /api/cfp
    • Mock DB: lib/mock-db/event-checklists.ts stores per-event organizer run sheets and status-changing milestones.
  • Native registration

    • GET /api/admin/venues/search?q=... proxies authenticated, rate-limited Places API (New) autocomplete and returns a narrow Ghana-only venue DTO without exposing the provider key.
    • POST /api/events creates a published, upcoming classified event and one open registration campaign as one application command; event format and DevCongress series are independent organizer fields, with meetup as the backwards-compatible format default. A failed campaign write compensates by removing the new event.
    • Authenticated registration reads return managed_internally: true with the private campaign/guest list, or managed_internally: false for an existing historical event with no campaign. Unknown events remain 404, and reads never create campaigns or synthetic attendees.
    • On-site registration: /organizer-console/registration-display/:eventId is an authenticated Owner/Organizer display route that generates a local QR from the existing public registration URL. The same display is allowed on phone viewports, while the mobile Events workspace exposes a direct Show registration QR action. No attendee identity or check-in token is encoded in the QR.
    • register_for_event serializes capacity allocation per campaign in Postgres, rejects duplicate active emails, confirms within capacity, and automatically waitlists overflow. The legacy auto_confirm and waitlist_enabled columns remain fixed internal compatibility fields and are no longer organizer-controlled. cancel_registration_and_promote takes the same campaign lock, cancels the selected registration, promotes the oldest waitlisted guest when a confirmed place opens, and queues the promotion delivery in the same transaction.
    • The canonical public /r/:eventSlug form collects name/email only; legacy /register/:eventId links remain valid. The client performs a rate-limited /api/public/email-preflight before the final request so the button can show a real checking/submitting sequence, and the final route independently repeats the policy. Definite syntax, typo, disposable, null-MX, nonexistent-domain, or no-mail-domain results stop the new submission; DNS outages fail open. No historical attendee or check-in state changes. Attendee tables have RLS and no anonymous policies; all access goes through validated Hono routes.
    • Confirmation delivery is an outbox operation. Missing provider configuration or a Resend quota error never rolls back the attendee record.
  • Speaker management

    • Active Vue page: src/views/admin/AdminSpeakersView.vue
    • This is the event-scoped speaker identity/access allowlist. It is not the Event Archive and does not determine what is publicly published.
    • APIs: /api/events/[eventId]/speakers (GET/POST), /api/events/[eventId]/speakers/[speakerId] (DELETE)
  • Event Archive + requests

    • Active Vue pages: src/views/admin/AdminTalksView.vue, src/views/SpeakerTalkIntakeView.vue
    • Compatibility subroutes remain /talks/cfp, /talks/proposals, /talks/program, and /talks/backfill; the organizer UI presents the lasting records as Event Archive and the manual intake path as Archive Requests.
    • Archive items use the existing Talk persistence/API shape with kind: 'talk' | 'product_demo'. Older rows without kind normalize to talk.
    • The organizer proposal table shows every status by default and uses the shared app-styled All/Pending/Approved/Rejected dropdown above the table. The review drawer shows the complete proposal before selection and the complete archive record after completion/publication. Archive status actions are intentionally available only from that content-first drawer.
    • Approval and rejection are final. Both desktop and phone review flows require an explicit cannot-be-undone confirmation before the API transition; the phone confirmation is a safe-area-aware bottom drawer and the desktop confirmation remains an app modal. Selecting a proposal prepares a reproducible, event-bound 128-bit go.devcongress.org capability whose raw value is never stored; the unique stored hash resolves the compact code, while already-issued longer codes remain valid. Selection marks the delivery pending before recording the final decision, then dispatches the acceptance email immediately. A scheduled worker retries pending or failed selected-speaker deliveries with the same event/link idempotency key; accepted deliveries are never selected again. The table exposes Sending, Sent, and Retrying states rather than making delivery an extra organizer task.
    • Owners can create one submitted, owner-only test proposal per event to test the actual decision and delivery lifecycle. It is hidden from other organizers. The separate table-level Send test to me endpoint accepts only a client request UUID, derives the recipient from the authenticated Owner session, renders fixed synthetic speaker content for the current event, and records no speaker-link delivery state.
    • Owner-only delivery test proposals carry the internal note owner-only:test-speaker. The server removes them before calculating non-owner list counts and also denies non-owner decisions, link visibility, previews, and sends. This is an explicit test-data convention, not a public proposal field.
    • Generated private links resolve to the standalone /speaker-talks/:eventId/:token route before the organizer-console catch-all.
    • APIs: /api/events/[eventId]/talks (GET/POST), /api/events/[eventId]/speaker-submissions (GET), /api/events/[eventId]/speaker-submissions/test (Owner-only POST), /api/speaker-submissions/[submissionId] (PATCH), /api/events/[eventId]/speaker-intake-links (GET/POST/DELETE), /api/events/[eventId]/selected-speaker-emails/test (Owner-only POST), /api/internal/selected-speaker-emails/retry (scheduled POST), /api/events/[eventId]/speaker-intake-emails (POST), /api/events/[eventId]/speaker-intake/[token] (GET/POST), /api/talks/[talkId], /api/talks/[talkId]/reminder
  • Event feedback campaigns

    • Active Vue pages: src/views/admin/AdminFeedbackView.vue, src/views/FeedbackView.vue
    • APIs: /api/events/[eventId]/feedback-campaign, DELETE /api/events/[eventId]/feedback-campaign, /api/feedback/events/[eventId], /api/feedback/events/[eventId]/submissions
    • Answer contract: session ratings accept 1–5 or not_attended; the sentinel is counted separately and excluded from rating averages
    • Reporting model: lib/event-feedback-report.ts derives rating distribution, return intent, comments, missed sessions, and per-question averages from the full event response set without adding a chart dependency
    • Privacy contract: event feedback does not collect identity or persist browser/page context; a hashed random browser/event token provides soft duplicate protection
    • Supabase persistence: lib/supabase/feedback-campaigns.ts; unchanged questions are not rewritten on campaign updates. Actual question edits after responses return a 409 with recovery guidance; save/close failures appear in the shared toast and inline alert.
    • Mock DB fallback: lib/mock-db/feedback.ts
  • December 2026 annual-conference workspace and volunteer intake

    • Registration uses the monthly workspace heading, tab rail, and overview styles from src/styles/registration-workspace.css. Manager panels are Summary, Guests, Form & capacity, Emails, and Blasts. AnnualConferenceGuests.vue combines management registrations and admissions by ticket ID in one Guests list with optional camera scanning; the manager-only registration endpoint adds only the linked ticket identity. Owner-confirmed POST /registrations/:id/recover creates a linked registration through recover_annual_conference_registration; the source remains cancelled and repeated actions do not duplicate mail. Guests load all bounded server pages before client-side alphabetical/search/status filtering and eight-row pagination. The legacy /check-in route redirects managers to Guests but remains a minimal roster-only wrapper for delegated volunteers, without management queries or email exposure. Email history and confirmed failed-delivery retries reuse the protected ticket-email operations API, including free-registration deliveries with no order and waitlist notices. Blasts retain snapshot review and explicit queue confirmation; monthly scheduling/allocation controls are not exposed without matching annual backend support. Ticketing stays visible but disabled, with its APIs and records preserved.
    • Active Vue pages: src/views/admin/AdminAnnualConferenceView.vue, src/views/admin/AdminAnnualConferenceWorkPlanView.vue, src/views/admin/AdminAnnualConferenceFinanceView.vue, src/views/VolunteerIntakeView.vue, src/views/admin/AdminVolunteerView.vue, src/views/admin/AdminVolunteerDisplayView.vue
    • Organizer workspace: /organizer-console/annual-conference/:year, with an edition-scoped Work plan; Volunteers remains a 2026-specific compatibility workflow. Legacy Timeline links redirect to Work plan while retaining phase and task context. The workspace header uses one edition selector beside the Annual Conference label, places module navigation on its own row, and exposes future-edition creation as a secondary action. Desktop and tablet Kanban columns show newly created cards and cards that changed status or phase first, using server-managed board-entry metadata; existing cards retain their established order and phone layouts continue to use persisted sort_order.
    • Overview composition: an unboxed editorial edition brief makes the provisional date the page heading, keeps delivery progress visible, and reserves the only filled action for Work Plan. Venue and keynote facts open from the anchored Planning notes disclosure; Volunteers stays a quiet utility route, and workstream detail remains in the Work Plan.
    • Work-plan interface: a page-level phase selector defaults to the current or next delivery phase and scopes every downstream calculation; one consolidated phase panel combines phase context, completion, compact status controls, owner filtering, and filter clearing above an eight-workstream snapshot and a six-row paginated task ledger with no internal vertical scrollbar. Filter changes use a reduced-motion-aware View Transition so the ledger can resize without page wobble; the former task search strip is intentionally removed; creating, opening, or editing a task uses one accessible right-side drawer. Owner and collaborator controls display organizer names while retaining normalized email values in the submitted ownership contract; the collaborator summary shows at most two names plus a remaining count.
    • Work-plan API: authenticated GET, POST, and PATCH under /api/annual-conference/:year/work-plan; the platform owner and edition planning owner can edit every task, while organizers can edit only tasks where their membership email is accountable or collaborating. Volunteers continue receiving assigned tasks only and may change only their statuses. Task creation is available to the platform owner and edition planning owner. New or changed ownership is normalized to active organizer emails, collaborators are deduplicated, and accountable/collaborator overlap is rejected without blocking unchanged legacy Excel assignments. Migration 20260803120000_annual_conference_owner_override_and_identity_backfill.sql converts unique active-member legacy name matches to canonical emails and leaves ambiguous values untouched; a later explicit repair covers the organizer-confirmed Angela, Dede, Ernest, and Philipa mappings that could not be inferred safely.
    • Edition and phase APIs: authenticated edition list/create plus phase create/update/delete routes. The platform owner or latest edition's planning owner can create the next edition; the platform owner or each edition's planning owner manages its phases. New planning owners must be active organizers, and omission inherits the latest edition's owner.
    • Work-plan storage: relational Supabase annual_conference_editions, annual_conference_phases, and annual_conference_tasks, with lib/mock-db/annual-conference-work-plan.ts as the local JSON fallback. Database triggers reject overlapping phase windows, cross-edition phase assignment, target dates after phase end, and phase-end changes that would invalidate assigned tasks.
    • Work-plan phase contract: 2026 seeds Phase 1 for 1–31 August and Phase 2 for 1 September–19 December. Confirmed kickoff work is assigned to Phase 1 while the remaining tasks stay unclassified. Direct visits default to the current or next phase; an explicit Entire conference selection is stored as phase=all, so optimistic status updates retain the selected scope. Organizers can switch to another phase, No phase, or the entire conference. Future editions can use any number of phases; deleting one returns its tasks to No phase.
    • Initial data: 26-row Excel seed plus the manual Volunteer recruitment task in lib/annual-conference-work-plan.ts; confirmed Phase 1 responsibility updates override the original sheet; 19 December 2026 is provisional, the first named owner is accountable, remaining names collaborate, and All, TBD, or blank owners are unassigned
    • Finance workspace: /organizer-console/annual-conference/:year/finance is visible only when the response carries finance.view; it reports GHS planned budget, committed, paid, remaining, unpaid committed, outstanding expected income, received income, and category variance. Owners can open a right-side drawer to add budget lines or explicit expense/income records; the ledger's manual-income Manage flow records partial receipts, expectation changes, and unpaid cancellations while retaining their history. Selected Organizers are read-only finance viewers; Owners grant that view access in People & Access.
    • Finance APIs: GET /api/annual-conference/:year/finance, POST /api/annual-conference/:year/finance/budgets, POST /api/annual-conference/:year/finance/entries, PATCH /finance/entries/:entryId/expected, POST /finance/entries/:entryId/receipts, and POST /finance/entries/:entryId/cancel; finance reads require finance.view, mutations require an Owner session, and each mutation is audited.
    • Finance storage: relational Supabase annual_conference_finance_budgets, annual_conference_finance_entries, annual_conference_finance_income_amendments, and annual_conference_finance_income_receipts with GHS constraints and service-role-only grants; production receipt/amendment mutations use transactional Postgres functions and lib/mock-db/annual-conference-finance.ts remains the local JSON fallback. Entry source markers reserve source-linked rows for future ticket and sponsor modules.
    • Task contract: exactly Not started, In progress, Blocked, and Done; no reminders; receipts, reimbursements, approval policy, reconciliation, and multi-currency finance remain later slices.
    • Organizer compatibility redirects: /organizer-console/volunteers and /organizer-console/volunteer-display
    • Public form: /volunteer is the canonical standalone route without organizer navigation or app chrome; /volunteer/december-mega-meetup redirects to it for distributed-link compatibility. Its public copy is an evergreen DevCongress volunteer invitation, while submissions continue to feed the legacy 2026 campaign and organizer directory. Name and email are required; X and DevCongress Slack names are optional. The compact form retains touch-friendly controls, shared email preflight, and mandatory production Turnstile verification.
    • Volunteer display: /organizer-console/annual-conference/:year/volunteers/display is a protected, TV-safe DevCongress volunteer invitation with a high-contrast QR focal point and a responsive QR-first stack for smaller screens. It prefers the one active volunteer_intake short link and falls back to the canonical /volunteer URL when short-link storage is unavailable.
    • APIs: POST /api/volunteer-applications, GET /api/admin/volunteer-applications
    • Authenticated volunteer access: admin_memberships.role = volunteer; the SPA routes volunteers to Annual Conference without rendering the redundant global navigation tab, the API returns only tasks matched by accountable-owner/collaborator email, and volunteer mutations accept status-only changes on those assigned tasks
    • Security boundary: non-conference APIs retain the owner/organizer role gate, volunteer-applicant records remain organizer-only, and assigned-task responses redact internal_note
    • Storage: lib/mock-db/volunteer-applications.ts uses the existing app_json_documents Supabase compatibility store under the volunteer-applications key when server-side Supabase is enabled, with local JSON fallback for development
    • Abuse controls: mandatory production Turnstile using the volunteer_intake action, atomic cross-Worker client limits, shared email preflight, and one application per campaign/email
    • Follow-up campaign: server/routes/volunteer-follow-up.ts owns the 2026 queue, Owner launch/control, review-capability projections, private final-answer form, and scheduled drain. The read route only fetches persisted recipients and overlaps that read with Owner-only delivery health; it never reconciles applicants or sends mail. lib/supabase/volunteer-follow-up.ts reconciles the existing intake document into relational recipients during launch and scheduled recovery, and enrolls new or duplicate applications with an idempotent per-applicant insert. Failed intake enrollment is logged without applicant data and repaired by the isolated 15-minute scheduler, which reconciles draft, paused, and running campaigns independently of email configuration and quota. Migration 20260922200000_volunteer_follow_up_campaign.sql serializes daily claims and provides an expiring database drain lease. Each drain processes one invitation or outcome delivery; when outcomes are due while invitations are running, deterministic 15-minute windows reserve every other invocation for outcomes, alongside the existing 54/day cap, 35-email reserve, and fresh complete Resend usage check. lib/email/resend.ts reads Resend's /usage endpoint before a drain, accepts only non-negative safe-integer daily/monthly usage values, and fails closed without using provider plan limits. It stores and emits only safe stage/category diagnostics if pre-send work fails. src/components/VolunteerFollowUpPanel.vue is shared by desktop and phone Volunteers; its Owner-only status maps recognized, timestamped invitation/outcome drain results without rendering raw provider text, and treats old/non-running results as historical. The standalone src/views/VolunteerFollowUpView.vue uses a centered single-column layout, two identically styled question cards with borderless semantic fieldsets, a full-width motivation field with a live word counter, and compact native attendance radios with the app-pink selected state; live applicant submission retains its private token and Turnstile verification. The public /volunteer/follow-up/test route is a separate sandboxed test form: it verifies a test-specific Turnstile action, applies a separate public rate limit, and always discards answers without database writes, email, or queue work. Owners can open it in a new tab or copy its persistent go.devcongress.org short link; the legacy protected preview path redirects there. The initial skeleton follows the progress, role-specific setup/timeline, and inbox layout; background refresh failures leave the last loaded data visible. Directory, Reviews, and Campaign mount on their first visit and remain mounted while inactive so tab switches preserve loaded data and controls. The response window is 14 days after the Owner-configurable application cutoff; the initial cutoff is 30 September 2026, Accra time. The cutoff becomes immutable at launch because invitation copy promises it. Launch is explicit, never automatic on deploy. The invitation drawer contains the production email and its plain-text alternative only.
    • Reviews and Campaign are separate connected tabs on desktop and phone. GET /api/annual-conference/2026/volunteer-follow-up/reviews, review PATCH, and version-guarded outcome-message PATCH require volunteers.review_applications; their DTOs are allowlisted and invitations are reduced to sent/not-sent. Accepted and not-selected copy is append-only, service-role-only template data; review users edit it above the queue, while Campaign renders it read-only. The Owner campaign GET/settings/control/preview routes are Owner-only. Outcome preview accepts only a decision and loads persisted template copy server-side, never browser-authored text. Campaign payloads whitelist settings and operational delivery fields and never return the database drain lease token. Session identity scopes client query keys and Owner cache is removed on role downgrade.
    • Owner-only POST /api/annual-conference/2026/volunteer-follow-up/outcomes/test sends one saved-template sample to a specified or session email. VolunteerOutcomeTestEmail.vue uses the cached session identity, rate-limited sample sends, stable failure retry keys, and provider-acceptance feedback independently of audience eligibility. It does not modify campaign or applicant delivery state.
    • Selection decisions and outcome email delivery: the reviewer PATCH atomically saves review status, note, and expected-version decision without sending. The Owner previews a ten-minute eligible/excluded snapshot with immutable personalized payloads and must explicitly confirm; the transaction rejects cohort drift and deduplicates repeated confirms. Outcome delivery has separate pause/resume controls and shares the invitation lease and daily claim budget. Owner-only POST /api/annual-conference/2026/volunteer-follow-up/delivery-retries queues a single, already-failed definitive rejection through a service-role-only database RPC; it never sends immediately or changes either pause control. The Owner read model returns sanitized structured evidence and retry block reasons for both invitation and outcome records. See docs/features/volunteer-outcomes.md for the durable retry, webhook, and ambiguity contract.
  • Monthly system design

    • Active Vue pages: src/views/admin/AdminSystemDesignView.vue, src/views/SystemDesignPresenterView.vue, src/views/SystemDesignParticipantView.vue, src/views/EventView.vue, src/views/ArchiveEventView.vue
    • Storage: event.schedule rows with type system_design, optional public recap notes, and prompt-link resources
    • Draft generation: POST /api/events/[eventId]/system-design/draft reads public Google Slides prompt decks and returns extracted title, raw content, and a generated summary
    • Learning room: src/components/SystemDesignLearningRoomPanel.vue generates and reviews exactly five source-based questions on the saved-artifact page, including a directly adjustable per-question answer timer. POST /api/quiz/sessions/[sessionId]/presentation prepares a fresh room-scoped run after completion without expiring the reusable content; /present/system-design/:sessionId opens separately outside the admin shell. The public /learn/system-design/:code participant page receives a unique default room name and fixed avatar, then permits a device-authorized name edit only while the lobby is waiting.
  • Attendance analysis

    • Active Vue pages: src/views/admin/AdminAttendanceOverviewView.vue, src/views/admin/AdminAttendanceView.vue
    • The hub pairs the monthly ledger with one compact attendance-pattern panel: approved RSVP/check-in bars for the latest recorded events, an approved came/missed pie, and a small venue-planning footer. Completed native monthly campaigns derive this data from registrations/check-ins in bounded batch reads; future events remain unrecorded, and older events retain the Luma CSV fallback.
    • APIs: /api/attendance/monthly, /api/events/[eventId]/attendance, /api/events/[eventId]/attendance/import, DELETE /api/events/[eventId]/attendance
    • Mock DB: lib/mock-db/attendance.ts
    • CSV parser and summary metrics: lib/luma-attendance.ts

Per-Module Breakdown

Form QR presentation board

  • AdminPresentFormsView.vue owns per-visit selection and QR preparation. Present synchronously opens AdminFormBoardDisplayView.vue in a new tab without an opener; that view revalidates availability and displays form labels, QR codes and short links without fullscreen controls. Its explicit demo mode uses three non-live sample links without creating or opening campaigns. presentation-forms.ts selects only the chosen Accra month's event forms and avoids guessing among multiple monthly feedback campaigns.
  • Owner-only GET /api/admin/presentation-forms reuses listOpenShortLinkTargets without minting links. Selected forms use the existing short-link ensure endpoint, revalidated before presentation, with the same URL encoded and displayed. No new storage or migration.
  • Navigation lives in App.vue; owner gates protect /organizer-console/present-forms. Phone navigation hides the link, and the viewport policy redirects phone visits to organizer Home.
  • The audience view uses the approved photo-collage flyer layout with local April 2026 photos in public/presentation/, light QR dividers and stationary black-on-white codes. Source photos: Fido Dev-0440.jpg and Fido Dev-0509.jpg; no external image dependency.
  • Coverage: src/lib/presentation-forms.test.ts, server/admin-api-access.test.ts, src/organizer-viewport.test.ts, and the isolated presentation-board browser journey (month changes, empty selection, two/three tiles, new tabs, demo photos and preparation failure recovery).

Mock DB (lib/mock-db/)

  • Entry point: lib/mock-db/index.ts
  • Key functions:
    • readData<T>(filename) — reads data/{filename}.json, returns [] only when the file is missing, and throws on invalid/non-array JSON.
    • writeData<T>(filename, data) — serializes writes via a per-filename promise queue and replaces files through temp-file write + rename.
  • Non-obvious logic: The write queue chains promises per file key — concurrent writes to events and sessions can overlap, but concurrent writes to the same file are serialized inside one process. Atomic rename reduces partial-write corruption, but JSON files are still not a multi-process production store.
  • When Supabase is configured, shared-document read/write failures surface and fail closed instead of silently serving or writing local JSON. Production also never seeds a missing remote document from bundled local data; that bootstrap convenience is limited to non-production runtimes.
  • Each entity module (events.ts, talks.ts, etc.) exports typed helpers like getAll*, get*ById, create*, update*.
  • event-checklists.ts creates a default chronological run sheet on first read. Monthly events use the full CFP/program/post-event checklist, while quarterly meetups use the short setup checklist for creating the event shell and adding the G-Meet link. For existing events, it infers already-reached milestones from the current event status so completed events start with post-event tasks instead of a blank checklist. Event-specific disabled milestones stay visible but do not count toward progress or status backfill. lib/event-checklist-policy.ts identifies checklist-backed optional work shared by the server, overview, and event tabs.

Supabase (lib/supabase/, supabase/)

  • lib/supabase/browser.ts exports a browser client using VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY; auth session persistence is disabled because tester feedback does not use Supabase Auth.
  • lib/supabase/server.ts exports a server/admin client using VITE_SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY; keep the service key server-only.
  • vite.config.ts loads .env.local and injects it into the Hono dev server so local server routes can read Supabase secrets.
  • types/supabase.ts currently types the feedback tables by hand until generated Supabase types are introduced.
  • supabase/migrations/20260530000000_feedback.sql creates feedback_testers for the original testing loop and feedback_submissions for route-level and event-level feedback rows.
  • supabase/migrations/20260613000000_event_feedback_campaigns.sql adds event feedback campaigns, dynamic questions, structured answers, and event/campaign submission fields.
  • supabase/migrations/20260617001000_event_feedback_response_tokens.sql adds hashed anonymous response tokens so event feedback can reject repeat submissions from the same browser/event pair.
  • supabase/migrations/20260615000000_community_events.sql adds community_events, modeled from the current devcongress.org Astro meetup collection and seeded with the existing website meetup YAML entries.
  • supabase/migrations/20260620032000_event_series_type.sql adds a nullable series_type field (monthly, quarterly, special, or null for no series) so organizers stop relying on event titles to drive attendance and organizer workflow decisions. The Event Profile editor keeps both series and format drafts separate from persisted values, enabling Save profile only when there is a real change.
  • supabase/migrations/20260801020000_community_event_submissions.sql adds independent event taxonomy fields, a private relational proposal queue, and service-role-only transactional approve/reject functions with idempotent canonical promotion.
  • supabase/migrations/20260728000000_native_event_registrations.sql adds relational campaigns, attendee records, check-ins, retryable confirmation deliveries, and the atomic free-registration function. The organizer check-in endpoint has a paired DELETE mutation that removes only the selected check-in row for a correction while preserving the guest registration.
  • supabase/migrations/20260729010000_registration_waitlist_promotion.sql fixes the automatic-allocation policy at the database boundary, adds promotion deliveries, and performs cancellation plus oldest-first waitlist promotion atomically.
  • supabase/migrations/20260728020000_security_hardening.sql removes direct anonymous feedback access, adds atomic public rate-limit buckets, moves CFP proposals to private relational rows with database-enforced active-proposal uniqueness, moves speaker links to relational hash-only state with atomic claim/consume/release functions, and revokes organizer sessions after membership role/status changes.
  • supabase/migrations/20260729000000_fix_public_rate_limit_timestamp_ambiguity.sql repairs the distributed limiter for projects that already applied the security migration by replacing its ambiguous current_time variable with an explicit timestamptz value.
  • supabase/migrations/20260615001000_meetup_media_bucket.sql adds the public meetup-media Supabase Storage bucket for selected image uploads.
  • Feedback tables have no anonymous select/insert privileges after the security migration; all public submissions pass through validated, rate-limited Hono routes using the server-only service role.
  • Row-level security allows public reads of community_events only when publish_to_website = true; trusted organizer writes use the server-side service role.
  • /api/health and /api/health/supabase expose only minimal public readiness state.
  • /api/health/data-sources, /api/health/supabase/community-events, and /api/health/supabase/storage require owner access before returning internal diagnostics. The data-source response includes only missing / weak / ready shared-secret preflight states, never secret values.
  • /api/events reads, writes, and removes Supabase community_events when APP_DATA_SOURCE=supabase is set with credentials. Configured Supabase query failures surface instead of silently serving stale local JSON; JSON fallback is limited to local/dev runtimes that explicitly disable or omit the Supabase data source.
  • The hosted community_events projection remains separate from compatibility Talk archive records. Until those records move to a relational archive source or are joined into that projection, a Supabase-backed public meetup response may not include archive items that exist only in the compatibility store.
  • Active Luma preview/import routes are removed because deployed Cloudflare Workers cannot reliably extract the public pages. Historical Luma metadata and attendance CSVs remain compatibility data.

Hono Server (server/)

  • Entry points:
    • server/app.ts exports the fetch-compatible Hono app used by Vite dev server.
    • server/index.ts starts Bun in production, serving /api/* through Hono and all other paths from dist/.
  • Annual Conference module: server/annual-conference-service.ts owns edition/phase/task use-case sequencing and audit events; server/annual-conference-repository.ts selects and normalizes Supabase or mock persistence once per request; lib/annual-conference-access.ts is the capability, visibility, redaction, and task-authorization policy; lib/annual-conference-read-model.ts produces the shared indexed phase projection; and src/composables/useAnnualConferenceWorkspace.ts owns the Work Plan query, phase scope, refresh, task selection, and task-update lifecycle.
  • Current active APIs:
    • /api/health and /api/health/supabase (minimal public readiness)
    • owner-only /api/health/data-sources, /api/health/supabase/community-events, and /api/health/supabase/storage
    • /api/public/meetups, /api/public/meetups/[slug], /api/public/meetups/[slug]/talks, /api/public/events, /api/public/event-submissions
    • /api/auth/session, /api/auth/admin/exchange, /api/auth/admin/callback, /api/auth/logout
    • /api/admin/organizers, /api/admin/audit-log, /api/admin/event-submissions, /api/admin/events-preview
    • /api/overview
    • /api/attendance/monthly
    • /api/feedback/inbox, /api/feedback/inbox/[feedbackId]
    • /api/events, including native event creation, registration, checklist, and historical attendance routes
    • /api/registration/events/[eventId]
    • /api/cfp/events/[eventId]
    • /api/talks
  • Public website contract: /api/public/meetups* reads Supabase community_events when the server Supabase runtime is enabled; a configured query failure does not silently serve stale local data. Local JSON plus explicitly published compatibility Talk data remains the development fallback only when Supabase is disabled. The compatibility API returns DevCongress-owned meetups only. Public collections have explicit response/query bounds, reject unsupported query keys, carry short cache headers, and are edge-cached by the Pages proxy only for queryless unauthenticated reads. Browser CORS is restricted to PUBLIC_API_CORS_ORIGINS; capability routes remain same-origin. The additive /api/public/events feed always returns published DevCongress events; approved, published events promoted from public submissions appear only when the fail-closed PUBLIC_EVENT_SUBMISSIONS_PUBLIC_DISCOVERY_ENABLED=true runtime gate is explicit. /api/public/event-submissions stores no canonical event until authenticated review and first requires the independent fail-closed PUBLIC_EVENT_SUBMISSIONS_ENABLED=true intake gate; cover intake consumes a pre-parse distributed limit, then verifies the event_submission Turnstile action and dedicated website hostname allowlist before signature/dimension validation and storage. New management links keep bearer material in a URL fragment and send it to same-origin API routes through authorization headers; legacy path routes remain only for already-issued links and are redacted from application logs. Intake and moderation functions atomically queue receipt/approval/rejection outbox rows; Resend dispatch happens only after persistence, uses stable idempotency keys, and records queued/accepted/failed state for organizer retry without repeating the decision. Approved amendments transactionally update the canonical event, then clear reviewed registration-page findings and rebaseline the monitor without performing a source fetch or Slack notification; the next automatic comparison follows the event-date cadence, while Check now remains available for explicit early verification. Existing /talks, talks, and talk-count names remain for compatibility; each returned archive item may add kind, with a missing value interpreted as talk, so product_demo can be rendered without breaking older consumers. /api/public/archive* returns narrow public archive payloads, and /api/public/home excludes attendance identity under the same short public cache policy. Internal /api/* routes remain organizer-gated except explicit public intake routes.
  • Public website verification: pnpm verify:public-api validates the public meetup response shape against the current devcongress.org Astro meetup schema expectations, plus CORS headers, cache headers, detail lookup, and talks lookup against PUBLIC_API_BASE_URL before the Astro website is wired to consume it.
  • Public event consumer preview: authenticated organizers open /organizer-console/website-preview/events from Event Management to inspect the complete published collection returned by the private, non-cacheable /api/admin/events-preview contract. Every card opens /organizer-console/website-preview/events/:slug, backed by /api/admin/events-preview/:slug. This preview intentionally includes private-beta submissions excluded from /api/public/events; it remains organizer-gated and does not expose unpublished drafts.
  • Auth note: All organizer routes use Supabase Google OAuth plus app-owned HTTP-only sessions stored in admin_sessions; owner-only organizer email management lives at /organizer-console/organizers, and owner-only audit review lives at /organizer-console/audit-log. Local development uses the same Google flow and membership allowlist as hosted environments. Missing Supabase auth configuration fails closed and never creates a shared-password owner session.

Vue App (src/)

  • Desktop header overflow uses src/navigation-fit.ts to retain the leading permission-filtered links and reserve space for an anchored More disclosure. App.vue measures intrinsic labels independently of the visible prefix, remeasures after fonts and resize, and restores focus when destinations move. The full-width menu is selected only at the 960px visual breakpoint; organizer phone routing still uses 767px.
  • src/styles/underline-section-nav.css supplies the shared 46px target, bottom-aligned label, and single 2px active divider segment for WorkspaceSectionNav, AnnualConferenceNav, event Registration, and Audit Log. The Audit Log fixture uses the same underline appearance while segmented loading controls retain their existing treatment.
  • The capture adapter measures structural table cells/list items through their children and bare text ranges so record cards retain visible fields. After artifact promotion it restarts the isolated capture server, then verifies exact rendered leaf counts and dimensions from a fresh module graph before completing the manifest. Representative runtime screenshots include phone and desktop Orders cards.
  • CI runs tools/verify-boneyard-manifest.mjs before the full-history secret scan. It verifies completed artifact hashes and every raw hash-inventory row, including duplicate or unused rows, before the exact manifest-path/full-row exception is applied to the generic API-key rule. Other keys, paths, and secret rules retain their normal detection. The integrity check covers the checked-out manifest, not every historical artifact version.
  • DESIGN.md records the implemented visual contract for future sessions. AppDropdown.vue enforces 44px minimum trigger/option heights on coarse pointers while retaining dense desktop variants and measured menu placement.
  • WorkspaceSectionNav.vue provides the shared Ticketing and Registration section row. Ticketing sections are Overview, Orders, Delivery, Sponsors, and Testing, selected through validated URL query state. Stable route keys retain mounted workspaces, filters, and drafts; leaving a section closes its drawers and transient portalled controls without discarding form values. The row reveals the active link horizontally on resize and displays an overflow cue on phones.
  • OrganizerBreadcrumbs.vue uses organizer-breadcrumbs.ts to build role-aware parent trails for supported organizer routes. Cached query data supplies labels without extra requests, unknown names use neutral fallbacks, and only the final leaf is current. Phone trails retain the nearest parent/current workspace and route conference parents to the same year's mobile Overview. Existing event return context and public/standalone exclusions remain intact.
  • Ticketing's existing route is allowed on phones and preserves year, section, and filters across viewport changes. Mobile Conference Overview links to it only when the existing role/capability policy allows access. Phone Orders use cards, forms stack, and drawers keep safe-area padding and visible close controls. Registration uses the same section-row component; no extra bottom-navigation destination is added.
  • Shared controls use AppDropdown.vue for single choice and AppMultiSelectDropdown.vue for multiple choices. Native <select> menus are prohibited in active Vue views, components, and loading fixtures by src/form-design-system.test.ts; styling tokens alone cannot supply the shared menu behavior. Use portalled menus in clipped panels/drawers. The shared display token points to Bricolage Grotesque and ordinary UI text uses Source Sans 3.
  • src/main.ts starts initial router resolution before mounting Vue, preserving the server/Vite-injected route-specific boot screen through a hard-refresh route load. It mounts src/PublicApp.vue for deliberate public exceptions and lazy-loads src/App.vue only for organizer/protected routes, then installs Vue Router, the shared TanStack Query plugin, and the delegated pointer-only button press-feedback system from src/button-press-feedback.ts.
  • lib/app-boot.ts keeps the organizer first-paint copy for protected and unknown paths while rendering registration, CFP, feedback, speaker-intake, volunteer, and System Design learning-room skeleton variants for public paths. server/index.ts, server/app.ts, vite.config.ts, and public/_worker.js select the same variant before Vue mounts so local Bun, Vite, Hono, and Cloudflare Pages do not regress to the organizer loader.
  • src/components/ui/BoneyardPageSkeleton.vue resolves each initial loading boundary by its stable section ID in src/boneyard/sections/, including tab, role, and board/ledger variants. BoneyardPageSkeletonFixture.vue renders that section's source-backed structure; complex work-plan, directory, QR-board, and registration-summary fixtures reuse the loaded layout's components or CSS. The same natural fixture geometry drives capture and runtime sizing, while page previews budget ancestor padding and remain inside the available viewport. Inline panels retain their own footprint; previewMaxHeight supports an explicit capped preview when a panel begins below the fold. Orders uses min(25rem, 60svh) so its loading cards remain visible when scrolled to on short phones. Volunteer intake mounts directly because it has no initial data request.
  • src/router.ts lazy-loads routed page components with dynamic imports, keeping the shell and route guard eager while splitting public pages, organizer workspaces, quiz views, and fallback pages into route chunks. Once organizer auth resolves, its route guard applies the shared viewport policy before importing a desktop organizer page. The mobile organizer home reuses the cached events and Annual Conference work-plan queries to prioritize today's event action plus blocked, overdue, unassigned, or active conference tasks; volunteer sessions omit event reads and receive only server-filtered assigned work. Post-auth phone routing treats a bare Annual Conference overview as a broad landing request and opens mobile Home, while preserving exact event, check-in, filtered task, desktop, and volunteer destinations.
  • src/organizer-viewport.ts is the single organizer breakpoint and route-policy source. Authenticated phone routes resolve to Mobile Ops while preserving event identity and mapping supported desktop sections to mobile Overview, Guests, or Submissions. Annual Conference redirects carry the edition section plus supported phase, status, workstream, owner, and task query context in both directions. Redirects replace only the viewport-incompatible history entry; user tab and task selections push their own URL state, so browser Back restores the prior meaningful view. Unsupported sections and malformed query values deliberately fall back to Overview or default filters.
  • src/App.vue provides the protected organizer shell/nav, mounts AppToaster, and keeps organizer pages directly beneath the primary navigation or event tabs; it does not fetch an active classic Quiz session. The shell presents Annual Conference as a top-level organizer workspace while keeping Volunteers edition-scoped beneath December 2026, and gives protected QR displays the same standalone treatment so they cannot inherit organizer navigation or the phone ops view. Its cream, 68px inner header, 40px logo, mixed-case text links, pink active underline, and navigation dropdown follow website main; EMS destinations and role rules stay application-owned. The outer header is 69px including its divider, and the phone/event-tab offsets share that token. The visual navigation breakpoint is separate from the 767px organizer route policy. During a direct protected-route load, the shell uses the same AppBootScreen content as the organizer pre-JavaScript first paint while the organizer session resolves. It redirects organizer routes back to login if the cached/admin-session query later resolves unauthenticated and listens to the shared media query so crossing the phone/tablet boundary updates the canonical organizer route.
  • src/views/admin/AdminAuditLogView.vue exposes Email previews as an Owner-only subsection beside Email delivery, keeping email operations together rather than adding another primary organizer destination. Its embedded src/views/admin/AdminEmailPreviewsView.vue workbench reads the server-rendered active/planned inventory, keeps the scenario catalog and message metadata visible, and isolates each HTML email behind a same-origin sandbox document so the hosted app CSP remains strict while the email's inline-client styling remains faithful. The client also exposes the renderer's plain-text output and desktop/mobile email widths without any send mutation.
  • src/views/admin/AdminLoginView.vue presents the selected responsive Programme Cover sign-in as the single visual organizer-auth surface. It can be controlled by the protected-route gate and OAuth callback, while its ordinary login mode verifies that server-side Supabase organizer auth is configured before enabling Google. Session checking, callback exchange, non-organizer denial, service failure, and retry states all stay in the same access panel. src/lib/admin-auth-flow.ts maps response statuses to allowlisted generic copy, and src/admin-routes.ts rejects external or ambiguous redirect targets before a destination is stored or followed.
  • src/App.vue lazily renders src/components/AdminEventTabs.vue for event-scoped organizer routes only, keeping sub-section tabs stable while routed event pages change underneath without adding the tabs to the initial shell chunk. The tab bar reads the shared event-checklist query so a monthly System Design exclusion is rendered as a genuinely non-interactive tab and updates immediately when the checklist choice changes.
  • src/components/ui/AppToaster.vue wraps vue-sonner with the DevCongress editorial/ops toast theme; app code should call notify from src/lib/notify.ts instead of importing toast directly.
  • src/boneyard/capture.ts, src/bones/, and .auto-skeleton/manifest.json record the synthetic fixture input, responsive captures, and completed artifact hashes. pnpm skeletons:capture <section-id> captures one allowlisted fixture in its page/panel/drawer context at 390, 640, 768, 960, 1024, and 1280px after fonts/images/bounds settle. The tool stages artifacts, preserves unselected completed captures, verifies runtime dimensions, and promotes the manifest last with recovery backups. Completed IDs are a no-op unless explicitly refreshed; use --all --refresh only for an authorized complete rebuild. pnpm skeletons:registry verifies hashes and rebuilds the runtime registry. Keep loading states at the initial query boundary so loaded content remains visible during background refresh.
  • The earlier src/components/FeedbackBot.vue and src/views/RouteFeedbackView.vue route-feedback components remain in the repository for compatibility, but the active router and app shell do not expose or mount them.
  • src/views/FeedbackView.vue renders an event-scoped campaign from a minimal attendee-safe /api/feedback/events/:eventId payload; campaigns are open when manually set to active, or when draft with auto-open enabled and the event status is completed. Monthly meetups use lib/event-feedback-window.ts to open at event end and close 24 hours later by default; organizers can close sooner or reopen for a fresh 24-hour grace period without changing the database schema. The form does not request name or email. Session questions accept a 1–5 rating or a separate Did not attend state, and public submissions send a per-event random browser token so the server can reject duplicate submissions without collecting attendee identity.
  • src/views/ArchiveEventView.vue reads /api/public/archive/:eventId, shows uploaded recap photos and quarterly-only raw links shared during the meetup, hides the empty talk archive for talkless quarterly meetups, and shows the community “Give Feedback” CTA only while that public archive payload says the form is open.
  • src/views/DashboardView.vue renders the community hub from /api/public/home, using only public counts, recent published talk cards, and an optional public CFP event pointer instead of the broad organizer overview aggregate.
  • src/views/EventsView.vue is the authenticated consumer-preview collection. It mirrors the DevCongress website event-listing shape, reads /api/admin/events-preview through the shared TanStack Query cache, includes published private-beta submissions, and routes every card into the matching preview detail.
  • src/views/EventView.vue is the authenticated consumer-preview detail. It consumes /api/admin/events-preview/:slug to render the event cover, schedule resources, speakers, status action, past-event photos, and recordings. Third-party media is embedded only for exact HTTPS YouTube or Vimeo player hosts inside a restricted iframe and matching Content Security Policy allowlist; other validated URLs remain explicit external links.
  • src/views/ArchiveView.vue filters completed events by year, query, topic, and speaker from /api/public/archive; archive search and speaker filters also look at saved schedule metadata so system-design recap text and facilitators still help people find the right meetup.
  • Shared event reads now normalize stale lifecycle states from the saved dates before the client sees them, so a published meetup that has already ended resolves to completed across the archive, dashboard, attendance, and feedback flows even if the stored row was left on live or another pre-event status.
  • src/views/NotFoundView.vue is mounted by the final Vue Router catch-all route for unknown client paths.
  • src/views/admin/AdminMobileOrganizerView.vue is the lightweight phone Home and does not load event or conference operating data. The mobile menu exposes Home, Events, and Conference as separate destinations. src/views/admin/AdminMobileEventsView.vue owns the complete event list and opens AdminMobileEventView.vue for focused Overview, live Guests, and presentation Submissions. The Submissions tab shows the stable reviewable proposal total, while pending, selected, and not-selected filters use the shared src/lib/speaker-submission-counts.ts projection so their pink counters move with each decision; the desktop presentation review filters consume the same projection. Check-in mode opens the standalone AdminMobileCheckInView.vue door-mode screen with name/email search, first-letter filtering, progress, full-width check-in actions, and confirmed-guest undo controls. Email guests opens AdminMobileEventBlastsView.vue, which reuses the existing confirmed-audience, 100-recipient, capacity-reserve, scheduling, rendered-preview, persisted-provider-draft, audited-send, and prepared-failure retry contract; shared starter copy lives in src/lib/event-blast-workspace.ts. src/views/admin/AdminMobileAnnualConferenceView.vue is a standalone role-specific workspace: organizers receive Overview, filtered Work Plan, Volunteers, edition controls, and full task create/edit flows; volunteers receive only assignment-scoped Overview and My Tasks with status-only controls. It reuses the shared workspace controller, API capabilities, task form, and task drawer without loading desktop route chunks. The shared RegistrationAlphabetFilter.vue exposes only initials present in the guest list through 44px touch targets, while src/lib/registration-checkin.ts combines that selection with name/email search and stable alphabetical ordering. Existing events without a native campaign show a bounded historical-registration explanation instead of search controls or synthetic guests. Cancellation/removal remain in the full event console; canonical mobile routes prevent hidden desktop route chunks from loading behind them.
  • src/views/admin/AdminAttendanceOverviewView.vue renders the monthly attendance ledger and a compact two-chart pattern panel from /api/attendance/monthly. The charts compare approved RSVPs with check-ins across recent recorded events and summarize selected-year approved RSVP outcomes; native monthly campaigns supply registrations/check-ins automatically, while older campaign-less meetups remain eligible for Luma CSV import. Its people panel defaults to regular attendees with at least two actual check-ins and restores the registered, came, rate, and last-seen summary. A separate Never came view lists every person with at least two approved RSVPs and zero check-ins, excluding pending and declined registrations. The people table uses a capped, keyboard-focusable scroll area with a sticky column header so long follow-up lists do not lengthen the entire page.
  • src/views/admin/AdminFeedbackOverviewView.vue opens the Feedback Hub directly into event feedback reports grouped by selectable year and period. Reports default to the current month when that period exists, and event rows keep a lighter identity block on the left with a full-width stat strip plus end-aligned action on desktop.
  • src/views/admin/AdminEventsView.vue reads the organizer event list through the shared TanStack query layer, shows focusable detail popovers for the compact lifecycle legend, creates and publishes classified native events with open registration campaigns, auto-generates an editable website slug from the event name, keeps a two-hour default event duration while preserving deliberate duration changes when the start moves, uploads a selected/compressed cover after the event record exists, and invalidates the event-list plus overview queries after creating a new event.
  • src/components/ui/AppDatePicker.vue supplies the organizer forms with one compact, app-centric date/date-time control. It displays dates as DD/MM/YYYY, uses Monday-first weeks, caps its body-level popover at 344px, opens above or below the trigger using the visual viewport, clamps horizontally on narrow screens, and scrolls internally when neither side can fit the full calendar. Inline errors are exposed through the trigger's accessible error state and description.
  • src/components/ui/AppCopyButton.vue supplies one stable-width copy-link interaction across organizer workspaces. It exposes idle, copying, and copied states, keeps the accessible action name stable while announcing progress through a dedicated status region, uses the app's green checked confirmation treatment, and locks repeat input until the caller returns to idle. src/lib/clipboard.ts confirms either the modern Clipboard API write or the checked legacy fallback before a view may enter the copied state. Its opacity/transform feedback is brief and disabled under reduced motion.
  • src/views/admin/AdminAuditLogView.vue reads audit rows through the shared TanStack query layer and renders its registered audit-log skeleton while the initial route data is loading.
  • src/views/admin/AdminEventView.vue invalidates shared event/overview queries after checklist, program-outline, photo-link, and media-upload mutations so status, schedule, and media changes stay visible across routes.
  • src/lib/meetup-media-client.ts centralizes browser-side meetup image validation, compression, and upload helpers so organizer create/edit surfaces share the same storage limits and encoding behavior.
  • src/lib/event-form.ts centralizes Zod validation for organizer event creation so the create form and /api/events server endpoint share the same required-field, slug, date, and URL rules. Its date helpers synchronize the default event range and require an optional end time to be strictly after the start.
  • src/views/admin/AdminAttendanceView.vue uploads/replaces a Luma CSV and renders post-event import metrics, source/ticket breakdowns, checked-in guests, and approved no-shows.
  • src/views/admin/AdminEventView.vue renders the shared chronological event checklist from /api/events/:eventId/checklist; checking status milestones can advance the event state, while the status dropdown remains available for manual correction. Unpublished events can disable incomplete checklist milestones that do not apply to that event. The incomplete monthly System Design milestone is the deliberate published-event exception: Not this month persists its exclusion and disables that event's System Design navigation, while Include this month reverses it.
  • src/views/admin/AdminEventView.vue also manages optional program outlines in event.schedule, letting organizers add structured time/title/type/lead/description/resource rows when a meetup has a run of show. Each editing row has accessible move-up and move-down controls, so a live organizer can adjust the running order before saving. A separate quarterly-only Shared links panel lets organizers paste raw recap URLs without titles; those links are saved into a dedicated schedule bucket and preserved when the outline is edited. The editor includes a monthly system-design scenario helper for Google Slides prompt decks, empty outlines are allowed, and event feedback can reuse saved schedule rows as activity prompts.
  • src/views/admin/AdminFeedbackView.vue keeps event feedback setup private while restoring deliberate organizer-only attendee-form tools: preview the current draft, copy the live form URL, open a protected TV-safe QR display, close an open form immediately, or reopen a closed form for 24 hours. Copy-link actions use the shared icon-led copying and checked-success feedback. A manually published campaign can show its QR immediately, subject to its close boundary.
  • Event-feedback reporting treats every submission as anonymous, keeps missed-session counts separate, and calculates averages from valid numeric ratings only. Historical identity fields are not returned to the organizer surface. The event report renders dependency-free aggregate charts from all loaded submissions; individual responses are kept out of the page and are available through a full CSV download with one submission per row and every configured question as a column. lib/event-feedback-export.ts owns deterministic response ordering, CSV escaping, and spreadsheet-formula neutralization for attendee-provided values.
  • src/views/admin/AdminSystemDesignView.vue calls /api/events/:eventId/system-design/draft when organizers click Generate Draft with a Google Slides prompt URL, fills the scenario title if it was blank, writes the returned summary into the full-width public recap field, and switches back to a saved/read-only state after persistence with explicit edit/remove actions for each saved scenario. When the event already has a matching system-design slot in the program outline, this editor updates that existing row in place instead of appending a duplicate system_design row at the bottom. A saved source also mounts SystemDesignLearningRoomPanel directly on this workspace, including for completed meetups, while the presenter opens in a separate organizer-protected tab. Before anyone joins, organizers choose generated aliases or attendee-entered room names; the setting locks after the first participant.
  • src/views/admin/AdminEventView.vue also manages event media: organizers can upload selected cover/photo images to Supabase Storage or add website-compatible { url, type } links where type is image for direct media or folder for shared galleries.
  • Legacy Next pages/components remain in app/, components/, and hooks/ as a reference while routes are ported.

Quiz State API (server/quiz-state.ts, server/app.ts)

  • Key function: GET /api/quiz/state?sessionId=&userId=
  • Facilitator commands: protected POST /api/quiz/sessions/:sessionId/release selects the next unreleased System Design question in reviewed order, while POST /api/quiz/sessions/:sessionId/reveal controls when its answer and explanation appear.
  • Non-obvious logic: GET /api/quiz/state is read-only. Attendee requests do not receive live answer distribution before reveal; the standalone authenticated presenter opts into aggregate option counts and percentages with presenter=true. Its shared-screen UI uses the current cream, paper, ink, pink, and yellow design system, with a fixed four-column vertical aggregate chart that highlights the correct option only after reveal. Per-answer respondent identities are not returned. On finish, the presenter receives the top-ten leaderboard with Navii avatars; a System Design attendee receives only player_standing for the requesting participant and never the full leaderboard.
  • correct_index is stripped from current_question in the state payload; player-specific reveal data is returned through player_result.correct_index after answering.

Scoring (lib/scoring.ts)

  • calculatePoints(basePoints, timeLimitMs, timeTakenMs, isCorrect) → speed-scaled score
    • Formula: base × (0.5 + 0.5 × timeRemaining/timeLimit) — instant = 100%, deadline = 50%, wrong = 0
  • calculateStreakBonus(streakCount) → bonus from STREAK_BONUSES map (2→100, 3→200, 4→300, 5+→500)

Legacy Role Store (hooks/use-role.ts)

  • Zustand store with persist middleware — saves to localStorage key devcon-comm-role-storage

  • Holds role: Role and speakerEmail: string | null

  • Convenience hooks: useRole(), useSpeakerEmail()

  • Legacy-only. The new Vue/Hono app has no migrated auth/session layer yet.

  • Sets sessionEnded = true on HTTP 404 (session deleted or finished)

Design System (lib/design-system.ts)

  • Exports designSystem object with colors, quizColors, fonts, styles, spacing, animations
  • Helper functions: getStatusBadge(status) → { className, label }
  • JS-side mirror of the Tailwind theme in tailwind.config.ts — keep both in sync when rebranding
  • The active organizer UI uses the established devcongress.org light palette: cream canvas, white and warm paper, saturated yellow and pink identity/state cues, and strong ink borders and shadows.
  • src/styles.css owns the shared .editorial-* and .ops-* primitives, including the boxed navigation and raised panel treatment used across organizer routes.
  • @fontsource/inter supplies display/body type at 400–800. IBM Plex Mono remains limited to labels, statuses, compact controls, technical values, and live codes at 400–700.
  • Shared font-weight roles are body 400, supporting emphasis and form values 500, mono labels and actions 600, headings and major metrics 700, and page/hero display 800. font-synthesis: none prevents browsers from fabricating heavier faces.

Configuration

Variable / Property Default Purpose
DEFAULT_TIME_LIMIT 20 (seconds) Per-question time limit
DEFAULT_POINTS 1000 Base points per correct answer
STREAK_BONUSES {2:100, 3:200, 4:300, 5:500} Bonus points per consecutive correct streak
VITE_SUPABASE_URL unset Supabase project URL for browser and server clients
VITE_SUPABASE_ANON_KEY unset Browser-safe Supabase anon key
SUPABASE_SERVICE_ROLE_KEY unset Server-only Supabase service role key for trusted admin operations

All constants are in lib/constants.ts.


Key API Flows

CFP Submission

POST /api/cfp
  body: { event_id, kind: 'talk' | 'product_demo', speaker_name, speaker_email, title, topic, abstract, bio }
  → creates a presentation proposal for organizer selection
  → accepts submissions only for upcoming monthly events with CFP open
  → does not create an archive item or require a prior speaker allowlist row

GET /api/events/[eventId]/speaker-submissions
  → organizer-only presentation proposal inbox for the event

PATCH /api/speaker-submissions/[submissionId]
  body: { status: 'selected' | 'not_selected', internal_note?, expires_in_days? }
  → records the organizer decision
  → selecting generates a one-time completion link that preserves the proposal kind

Annual Conference CFP and Logistics

POST /api/cfp/conferences/[year]
  body: { speaker_name, speaker_email, bio, title, topic, session_type, abstract, learning_outcomes[3..5] }
  → validates the fixed conference track and session-type lists
  → stores one proposal in annual_conference_speaker_submissions, not speaker_submissions
  → reuses the normalized annual_conference_speaker_profiles identity for the email
  → permits several different titles from one speaker and reviews each row independently

PATCH /api/annual-conference/[year]/speaker-submissions/[submissionId]
  body: { status: 'selected' | 'not_selected', internal_note? }
  → an atomic status compare-and-set accepts once and creates the proposal-bound programme session before follow-up
  → issues a hash-only private capability and immediately attempts the acceptance email
  → an incomplete email remains visible and can be retried with an atomic rotated-link swap

PATCH /api/annual-conference/[year]/speakers/logistics-deadline
  body: { deadline }
  → organizer-controlled cutoff applied to every active workspace for the edition

GET|POST /api/conferences/[year]/speaker-intake/[token]
  body: { slides_url, availability_confirmed, technical_requirements, workshop_prerequisites, required_software_equipment, participants_need_laptops, preferred_workshop_capacity }
  → verifies token hash, edition, current proposal link, accepted session, and deadline
  → updates the same accepted session repeatedly so speakers can save drafts and return
  → never asks the speaker to resubmit title, track, type, abstract, bio, or learning outcomes

Manual Archive Entry (Admin)

POST /api/events/[eventId]/talks
  body: { kind: 'talk' | 'product_demo', speaker_name, speaker_email, title, topic?, abstract?, bio?, github_username?, slides_url?, publish? }
  → writes the existing Talk compatibility record with the requested archive-item kind
  → treats older records without kind as talk
  → creates/keeps the separate speaker allowlist row for that email as a compatibility side effect
  → creates an accepted item when slides_url is empty
  → creates a slides_received item when slides_url is present
  → publishes only when the organizer explicitly requests publish

Event Archive Intake

POST /api/events/[eventId]/speaker-intake-links
  body: { kind: 'talk' | 'product_demo', speaker_name, speaker_email, title, expires_in_days }
  → admin-only; creates a month-scoped, one-time Archive Request token
  → requires the event's Archive Requests workflow to be explicitly enabled
  → locks the event, invited identity, archive-item kind, and title into that token
  → only one matching active manual token may exist for the same event, email, and kind; different recipients may use the same expiry duration

POST /api/events/[eventId]/speaker-intake-emails
  body: { recipients: [{ program_item_index, speaker_email }], expires_in_days }
  → admin-only; accepts up to 100 unique eligible rows from the stored event schedule
  → requires the event's Archive Requests workflow to be explicitly enabled
  → validates each one-off organizer-supplied email while deriving name, title, kind, and event from the stored program row
  → does not write the supplied address back into the program outline or speaker allowlist
  → creates one fresh title-bound private link per unsent row and submits personalized entries through Resend Batch
  → records pending/accepted/failed state and provider IDs on the link, uses a stable idempotency key, and skips identities already accepted

GET  /api/events/[eventId]/speaker-intake/[token]
  → returns public event context and the locked kind only when the link is active

POST /api/events/[eventId]/speaker-intake/[token]
  body for archive_backfill links: { topic?, abstract?, bio?, slides_url? }
  body for selected_speaker_confirmation links: { slides_url }
  → manual-request identity, event, kind, and title come from the organizer-issued token, not browser-provided form fields
  → creates/keeps the separate speaker allowlist row for that invited email
  → July manual Archive Requests create accepted or slides_received compatibility Talk records from submitted details
  → the later selected-proposal flow creates the same compatibility record from the proposal, its stored kind, and the submitted slides URL
  → marks the one-time link as used after a successful submission
  → expired or used links return closed-link errors
  → never publishes an archive item directly from the public form

DELETE /api/events/[eventId]/speaker-intake-links/[linkId]
  → admin-only; removes a generated link from Archive Requests

Archive Publication Lifecycle (Admin)

PATCH /api/talks/[talkId]
  body: { status: 'accepted' | 'rejected' | 'slides_received' | 'published' }
  → requires admin cookie session when changing status
  → only published records appear in the public archive

POST /api/talks/[talkId]/reminder
  → logs an organizer slide reminder for accepted archive items without uploaded slides

System Design Learning-Room Lifecycle (Admin)

POST /api/quiz/sessions          → create session (status: 'draft')
PATCH /api/quiz/sessions/[id]    → partial QuizSession field updates

System Design Participant Join + Answer

POST /api/quiz/join              body: { join_code, device_id, purpose: 'system_design_learning' }
  → creates/finds User by deviceId, creates an anonymous System Design participant
  → increments User.events_participated when joining a new session
  → returns { session_id, user_id, participant_id }

The response includes a unique default room-scoped `display_name` and immutable participant-derived `avatar_seed`. Hosted sessions, questions, participants, and responses live in relational Supabase storage; local development keeps serialized JSON fallbacks behind the same domain repository APIs. Unique `(quiz_session_id, user_id)` and `(quiz_session_id, nickname_key)` constraints reserve participant identities, while `(question_id, user_id)` prevents repeat answers. Concurrent generated-alias conflicts reload and retry, while a participant-edited duplicate returns `409 nickname_taken`. Answer acceptance, scoring/streak updates, presentation reset/release/reveal, timed advancement, and question reorder operations use short PostgreSQL functions. Participant counts, answer distribution, leaderboard ranks, and requesting-player response state are aggregated in SQL instead of rebuilding them from shared arrays on each poll. While the room is waiting, the same device can send a validated replacement name to `PATCH /api/quiz/participants/[participantId]/name`; the endpoint closes once presentation starts. On participant phones, expiry of the local question countdown removes the answer grid and shows a waiting-for-reveal state; answer submission errors remain local to the question rather than becoming room-level failures.

GET  /api/quiz/state?sessionId=&userId=   read-only state fetch, polled every 1500ms
POST /api/quiz/answer            body: { session_id, user_id, answer_index }
  → records System Design participation and scores through the room runtime

System Design Question Management (Admin)

POST   /api/quiz/questions                 body: { quiz_session_id, question_text, options[4], correct_index, order_index, time_limit_seconds?, points? }
PATCH  /api/quiz/questions/[questionId]    body: Partial<Question>
DELETE /api/quiz/questions/[questionId]
POST   /api/quiz/questions/reorder         body: { session_id, question_ids[] }

Slides Upload Endpoints

POST /api/events/[eventId]/speaker-intake/[token]
  body for selected_speaker_confirmation links: { slides_url }
  → tokenized selected-speaker links accept public slide links without an organizer session
  → selected-speaker links create slides_received talks from the original CFP proposal