Alpha Readiness Gap Map: App + Admin + Merchant

Date: 2026-08-03 For: December 2026 invite-only Soft Alpha (small invited group, 1-2 San Diego venues, scheduled "lantern evenings," heavy monitoring). Alpha goals: validate the last-ten-feet meeting mechanic + measure whether people felt safe and comfortable, across everyone present rather than any single group. Source: three parallel read-only code audits (user app, admin portal, merchant portal), 2026-08-03. Verified by reading code, NOT by runtime execution, so some items are deploy/data questions, not code questions (flagged in Caveats).

Headline

Surface	State	One-line
User app (apps/web)	Strong	The core loop is code-complete end to end. Remaining items are operational + one copy bug, not missing features.
Admin portal (apps/admin/src/admin)	Mostly strong	Invites, user management, moderation, and live monitoring are genuinely wired. Gaps are on the supply side (adding venues, offer review).
Merchant portal (apps/admin/src/merchant)	Works only with a human in the loop	A merchant can go end to end ONLY if an admin manually bridges the middle. The application → approval → account seam is not wired in software.

The theme: the app that invited users touch is in good shape. The heavy-hitter work is on the supply/operations side (admin + merchant): getting venues in, wiring the merchant onboarding seam, and the offer flow.

Ranked heavy-hitter backlog

Tier 1 - Build these (alpha-gating)

Live status (2026-08-04): all Tier-1 on branch feat/admin-venue-creation (draft PR #788). #1 DONE (issue #786, spec docs/planning/specs/2026-08-04-admin-venue-creation-design.md): server-side admin-gated create/edit on venues-api (not in-portal OSM import, not client-rule loosening). #3 DONE (issue #789): lantern TTL = 2h (operator); copy + AGENTS.md aligned (server constant was already 2h; the 48h is doc-cleanup, and the separate location-history feature stays 48h). #2 DONE (issue #790): admin merchant-application review queue + human-in-the-loop approve (list/status endpoints on auth-api; Review prefills the proven CreateMerchantForm, which provisions + marks approved; reject; WIP label dropped). All Tier-1 build items landed this session.

1. Venue creation / seeding from the admin portal. Converged across ALL THREE audits. There is no admin UI to create or edit a net-new venue; venues only enter the venues collection via OSM import that lives in the web app / CLI, not the portal (components/venues/AdminVenuePicker.jsx is pick-only, config/ConfigVenue.jsx is import-config-only, services/api/venues/src/routes/import.js has no portal trigger). Without a venue: no lanterns can be lit, and merchants have nothing to associate an offer with. Fix: a minimal "Add / edit venue" admin form, or a reliable admin-triggered import for the 1-2 alpha venues. This de-risks the whole supply side.

2. Merchant onboarding seam: application-review → provision. The self-serve application (POST /merchants/apply → merchant_applications doc, works) is read-only to everything but the Firestore console; NO admin UI lists or approves it (apps/admin/src/admin/merchants/). Account creation is a separate, hand-retyped "Create Merchant" form still labelled "🚧 Work in Progress" (CreateMerchantForm.jsx:82), and the underlying createMerchantUser actually works. Plus a merchant can't self-associate a venue, so every offer create 400s VENUE_NOT_ASSOCIATED until an admin links a venue (admin-only endpoint, services/api/auth/src/index.js:168). Fix: an admin "merchant applications" view that approves → provisions the account via createMerchantUser AND associates a venue; drop the stale WIP label. (Survivable manually for 1-2 merchants, but this is the biggest merchant gap.)

3. Lantern TTL copy defect (2h vs 48h). Server TTL is 2h (services/api/lanterns/src/services/lantern.service.js:27) but the UI tells users "48 hours" in three places (LightLanternForm.jsx:369,375, LightLanternModal.jsx:297), and AGENTS.md's collections note also says 48h. Quick, but users are told the wrong thing about how long their lantern lasts. Fix: decide the intended duration (2h fits a "who's here right now" evening), then align copy + the constant + docs.

Tier 2 - Verify / operational (mostly not "build")

4. Live two-account E2E of the full app loop. Every endpoint (auth key-directory, sever, push functions) was verified by READING code, not runtime. The block-sever E2E harness on this branch (test/144-block-sever-e2e, PR #778) already runs signup → light → wave → accept → message → block+save-copy green on deployed dev; extend/confirm it covers push delivery to close the code-vs-runtime gap.

5. Pre-warm the alpha venue data in dev Firestore before the first lantern evening, so no user hits a slow/failing cold OSM import on first visit (apps/web/src/lib/venueService.js:369-466). Tied to Tier-1 #1.

6. iOS PWA push verification (#722). Push code is correct for Android/desktop Chrome; iOS Safari needs the PWA installed to home screen and there's no iPhone on the team. If any invited user is on iPhone, verify via a borrowed device / BrowserStack, or set expectations.

Tier 3 - Decisions / policy (may need little or no code)

7. Offer moderation gate (or explicit decision not to have one). Flagged by both admin + merchant audits: a merchant "Publish" flips an offer straight to active and it surfaces to nearby users with no independent review (services/api/merchants/src/routes/offers.js). Fine if alpha merchants are trusted; otherwise add a pending → approve state. At minimum, decide and document.

8. Monitoring auto-refresh. The venue-activity dashboard shows real live data (active lanterns/waves/connections now) but is manual-Refresh only (analytics/VenueActivityDashboard.jsx). Add a 15-30s poll so the team can watch a lantern evening without clicking.

9. Live venue discovery (decision). Venue lantern discovery is a one-shot refetch, not onSnapshot (deliberate, for pin de-identification), so a lantern lit while someone is already viewing the venue appears only after reopen/foreground (screens/dashboard/Dashboard.jsx). Decide if acceptable for a synchronized evening or add a light poll / pull-to-refresh.

Defer (not alpha-gating at 1-2 venues)

• Per-lantern / per-wave live moderation (moderation acts on users; ban the user).
• Merchant Photos tab uploader (stub; hero imagery via heroPhotoUrl).
• Merchant self-service venue linking (admin does it during onboarding).
• Self-serve merchant-application review beyond Tier-1 #2 (admin-creates covers 1-2 merchants).

Per-surface status (from the audits)

User app (apps/web): core loop code-complete

Signup+login (invite-gated), onboarding/profile, location+venue, lighting, see+wave, accept+real OS push, E2EE chat (Olm/Megolm), block/report (#144/#776): all WORK, wired to real Cloud Run + Firestore + FCM, no stubs or off-flags on the invited-user path. Risks: venue pre-warm (op), iOS push (device), TTL copy (bug), non-live discovery (UX), runtime-unverified (verification).

Admin portal (apps/admin/src/admin): ops wired, supply thin

WORKS: invite generation, user management (list/detail/ban/role/delete), moderation (live report cases, enforcement, appeals, manual ban), monitoring/analytics (live active-lanterns/waves/connections, manual-refresh). PARTIAL/MISSING: venue create (no portal path: Tier-1 #1), offer approval gate (none), merchant-application review (none; admin creates directly). Note: admin/feature-tracker/ is a GitHub-issues viewer, NOT a readiness manifest.

Merchant portal (apps/admin/src/merchant): end-to-end only with an admin bridging

WORKS: signup/application (MerchantSignup → merchant_applications), merchant login + portal (real role:'merchant' auth, createMerchantUser + set-password link, MerchantShell routing), offer authoring UI + POST /offers. BROKEN/BLOCKED SEAMS: application→account handoff (Tier-1 #2), venue self-association (offers hard-blocked), no offer moderation, Photos stub, stale WIP label.

Caveats

• All three audits are read-only (code, not runtime). Server endpoint behavior was confirmed to exist with correct client contracts, but not exercised live.
• Open deploy/data questions (not code): do the 1-2 San Diego alpha venues already exist in the dev venues collection? Are analytics-api + BigQuery healthy on dev? Is the push Cloud Function currently deployed and running on lantern-app-dev? These need a quick live/gcloud check, not a code change.