Developer Onboarding — Lantern

Last Updated: 2026-03-13

Welcome to Lantern! This guide walks you through everything you need to go from zero to your first pull request. Read it top-to-bottom on day one; bookmark it for later reference.

1. What Is Lantern?

Lantern is an anonymous, real-time people-meeting PWA anchored to physical venues. Users "light lanterns" at bars, cafés, and restaurants to signal availability — not with profiles or photos, but with presence. Think of it as a way to say "I'm here and open to meeting someone" without broadcasting your identity.

The product is currently in Pilot Mode — access is restricted to admin-role users while the core experience is refined. You'll see PILOT_MODE = true in apps/web/src/App.jsx.

For a deeper product understanding, read docs/ABOUT.md and docs/business/timelines/INITIAL_LAUNCH.md.

2. Prerequisites

Before you start, make sure you have:

Node.js v20+ and npm v8+ (node --version, npm --version)
Git configured with your work email
2FA enabled on your GitHub account (required — see Security Onboarding)
Access to the cattreedev/lantern_app GitHub repository
Firebase project credentials (ask a team member for .env.local values — do not create your own projects for an existing team setup)
Membership in the team's Slack/Discord channel for incident alerts

3. Repository Setup

Clone and Install

bash

git clone https://github.com/cattreedev/lantern_app.git
cd lantern_app
npm install

This is an npm workspaces monorepo. One npm install at the root installs dependencies for all workspaces.

Environment File

Once a maintainer has granted you roles/secretmanager.secretAccessor on the lantern-app-dev GCP project, one command populates everything:

bash

gcloud auth application-default login   # one-time
firebase login                            # one-time
npm run env:bootstrap

This fetches all 18 server-side secrets from GCP Secret Manager and the 7 public VITE_FIREBASE_* values via the Firebase Management API — no manual copy-paste required. The script creates .env.local from .env.local.example if it doesn't exist yet.

Three per-developer values you fill yourself in .env.local after running bootstrap: GH_PAT (your own GitHub PAT), GITHUB_OWNER (your username), and (optionally) GOOGLE_APPLICATION_CREDENTIALS.

Never commit .env.local. It is gitignored by design. See ENVIRONMENT_SETUP.md for the full guide (including the manual fallback for environments without gcloud / firebase-tools) and ../security/SECRETS_MANAGEMENT.md for the deep dive on the secret architecture.

Start the Dev Server

bash

npm run dev

Open http://localhost:5173. Check the browser console for:

🔥 Firebase initialized (local environment)
Project: lantern-app-dev

If you see that, you're connected correctly.

4. Codebase Architecture

Monorepo Structure

apps/
  web/           — Main Lantern PWA (React 19 + Vite)        ← you'll work here most
  admin/         — Admin dashboard (separate React app)

services/
  functions/firebase/  — Cloud Functions (Node 22)
  api/analytics/       — Analytics API (Cloud Run)
  api/venues/          — Venues API (Cloud Run)
  api/docs/            — Docs API (Express.js, Cloud Run)
  bots/discord/        — Discord bot for issue triage

packages/
  shared/        — Shared constants & utilities (@lantern/shared)
  forge/         — Shared BigQuery, Firestore, rate limiting, sanitization helpers

tooling/
  .storybook/    — Storybook configuration
  scripts/       — Build, lint, and utility scripts
  schemas/       — BigQuery event schemas

Web App Internals (`apps/web/src/`)

Path	Purpose
`App.jsx`	Root component — routing, auth gate, `PILOT_MODE` flag
`firebase.js`	Firebase initialization, environment detection, persistence
`screens/{domain}/`	Page-level components: `auth/`, `dashboard/`, `profile/`, `merchant/`, `frens/`
`components/`	Reusable UI components (mostly Storybook-backed)
`lib/`	Service modules: `auth.js`, `encryption.js`, `venueCacheManager.js`, etc.
`hooks/`	Custom React hooks

Routing

Lantern uses hash-based routing — no React Router. Routes are defined as window.location.hash checks in App.jsx:

Hash	Screen
`#/`	Dashboard (Lantern Hub)
`#/signup`	Sign up
`#/login`	Login
`#/profile`	Profile settings
`#/onboarding/profile`	First-time profile setup
`#/merchant`	Merchant dashboard
`#/merchant/new`	New merchant setup
`#/frens`	Friends
`#/feedback`	Feedback

To add a new route, update the route checks in App.jsx.

State Management

No external state library. State flows through React hooks and Firestore real-time listeners (onSnapshot). Auth state is managed in App.jsx via onAuthChange. Venue data is cached in localStorage via venueCacheManager.js.

Shared Package

packages/shared/ is aliased as @lantern/shared:

javascript

import { USER_ROLES, hasRequiredRole } from '@lantern/shared/auth'
import { isDevelopment } from '@lantern/shared/utils'

Zero-Knowledge Encryption

User personal data is encrypted client-side before reaching Firestore:

Algorithm: PBKDF2 (600,000 iterations) + AES-256-GCM
Keys are derived from the user's passphrase — never sent to the server
If a user loses their passphrase, their data is unrecoverable (by design)
Implementation: apps/web/src/lib/encryption.js

Critical distinction: The user's Lantern passphrase is also their Firebase Auth password AND their encryption key source. Do not conflate this with the admin portal password (see Admin Authentication below).

Firebase Collections

Collection	Purpose	TTL
`users`	Profiles (public fields + encrypted personal data)	Permanent
`lanterns`	Active check-ins	48 hours
`waves`	Meeting requests	7 days
`chats`	Messages	30 days
`venues`	Locations (imported from OpenStreetMap)	Permanent
`offers`	Merchant promotions	Permanent
`adminProfiles`	Admin-role–specific data + separate password hash	Permanent
`merchantProfiles`	Merchant-role–specific data	Permanent

Security rules live in firestore.rules (Firestore) and storage.rules (Firebase Storage).

5. Development Workflow

The Git Flow

All changes go through pull requests. Direct pushes to dev or main are not allowed.

feature branch → PR → dev → (auto-deploy to dev.ourlantern.app)
dev → PR → main → (auto-deploy to ourlantern.app)

Your daily flow:

bash

# 1. Branch off dev
git checkout dev
git pull origin dev
git checkout -b your-name/issue-123-short-description

# 2. Make changes, run tests
npm run dev           # local dev server
npm run validate      # REQUIRED before committing (lint + tests + coverage + audit)

# 3. Commit (reference the issue)
git commit -m "feat(auth): add passphrase strength indicator (fixes #123)"

# 4. Open a PR targeting dev
gh pr create --base dev --title "..." --body "..."

Before Every Commit

bash

npm run validate

This runs: lint → format check → unit tests → coverage → security audit → all workspace validations. Fix anything that fails before committing.

PR Rules

Target the dev branch (not main)
Reference the GitHub issue: fixes #123 or closes #123
Keep PRs small and focused — one feature or fix per PR
All CI checks must pass before merging (lint, tests, CodeQL, dependency scan)
Sensitive features (auth, encryption, payments) require a security reviewer

6. Key Commands Reference

Web App (most common)

bash

npm run dev              # Start dev server (http://localhost:5173)
npm run preview          # Production build preview (use for PWA testing)
npm test                 # Vitest in watch mode
npm run test:coverage    # Single run with 75% coverage threshold
npm run lint             # ESLint check
npm run lint:fix         # ESLint auto-fix
npm run format           # Prettier auto-fix
npm run validate         # Full validation — run before every commit
npm run build            # Production build
npm run storybook        # Component library (http://localhost:6006)

Other Workspaces

bash

npm run admin:dev                 # Admin panel (separate app)
npm run docs-api:dev              # Docs API
npm run analytics-api:dev         # Analytics API
npm run venue-api:dev             # Venues API

Useful One-Offs

bash

npx vitest run apps/web/src/lib/__tests__/encryption.test.js  # Run a single test file
npm run docs:dev                                               # VitePress documentation site
npm run changelog:consolidate                                  # Merge daily changelogs

7. Security Checklist

Complete this before your first commit to any production-connected system:

[ ] 2FA/MFA enabled on GitHub and any admin consoles you have access to
[ ] Least-privilege access — request only what you need via an access ticket
[ ] Read the security docs — docs/security/SECURITY_ARCHITECTURE.md and docs/security/ZERO_KNOWLEDGE_ENCRYPTION.md
[ ] No secrets in code — use .env.local locally, Secret Manager in production
[ ] PR process with SAST/SCA checks understood and configured
[ ] Added to incident Slack channel and informed of on-call rotation
[ ] Read vulnerability disclosure policy — docs/security/VULNERABILITY_DISCLOSURE.md

If you find a security issue, do not post it publicly. Follow the vulnerability disclosure process.

Full security onboarding checklist: docs/security/ONBOARDING.md.

Admin Authentication

Important: Admin portal authentication is completely separate from the Lantern app passphrase.

The admin portal has its own adminPasswordHash stored in the adminProfiles Firestore collection. This password is verified via Cloud Function (signInAdmin) and is independent of Firebase Auth. This design prevents an admin password reset from breaking their Lantern app encryption.

If you're being set up as an admin:

An existing admin creates your account
You receive a setup link (?mode=adminReset&token=xxx)
You set your admin portal password — keep this separate from your Lantern passphrase

8. Testing

Framework

Vitest + Testing Library React + jsdom
Coverage threshold: 75% on lines, functions, branches, and statements

Where Tests Live

apps/web/src/**/*.{test,spec}.{js,jsx}

Running Tests

bash

npm test                  # Watch mode (during development)
npm run test:coverage     # Single run with full coverage report

Path Alias

In tests, @ maps to apps/web/src/:

javascript

import { encrypt } from '@/lib/encryption'

Setup File

apps/web/test.setup.js provides DOM polyfills and mocks (e.g., IntersectionObserver). If a test needs a new global mock, add it here.

Writing Tests

Write tests for any new behavior you add
Unit test service modules in lib/ and hooks in hooks/
Component tests use Testing Library (prefer user-behavior queries over implementation details)
Run npm run test:coverage before your PR to verify you haven't dropped coverage below 75%

9. Documentation Practices

Where Documentation Lives

All documentation lives in docs/. Never put docs in src/ or other source directories. The canonical guide to what goes where is:

docs/engineering/guides/DIRECTORY_DEFINITIONS.md — read this before creating any new doc

Naming Conventions

Type	Convention	Example
Regular docs	`CAPS_SNAKE_CASE.md`	`FEATURE_NAME.md`
Worklog entries	`YYYY-MM-DD_FEATURE_OUTCOME.md`	`2026-03-13_WAVE_COMPLETE.md`
Audit reports	`AUDIT_YYYY-MM-DD.md`	`AUDIT_2026-03-13.md`

Changelog

Every PR should include a changelog entry. Add it to the daily section in docs/changelogs/dev/:

bash

# File: docs/changelogs/dev/dev-MM.DD.YYYY-v{version}.md

Use present tense: "Add feature" not "Added feature". See docs/engineering/guides/CHANGELOG_WORKFLOW.md for the full format.

Documentation Types

Type	Location	When to Use
Feature specs	`docs/features/{name}/`	New user-facing feature
Engineering guides	`docs/engineering/guides/`	How-to, workflows, operational procedures
Worklogs	`docs/worklog/`	Completed work (2+ hours of significant work)
Plans	`docs/plans/`	Roadmaps, large-scale planning
Architecture decisions	`docs/engineering/architecture/`	System design

10. Environments

Environment	Firebase Project	URL	Branch
Local	`lantern-app-dev`	`localhost:5173`	Any
Development	`lantern-app-dev`	`dev.ourlantern.app`	`dev`
Production	`lantern-app-prod`	`ourlantern.app`	`main`

Environment Detection

The app detects its environment via VITE_APP_ENV and hostname checks. When adding dev-only UI (debug panels, simulate buttons, etc.):

javascript

const hostname = typeof window !== 'undefined' ? window.location.hostname : ''
const isProductionEnv = import.meta.env.VITE_APP_ENV === 'production' || hostname === 'ourlantern.app'
const isDev = !isProductionEnv

Dev Utilities

In dev mode, useful utilities are exposed on window (via apps/web/src/main.jsx): location spoofing, venue testing, and cache management. Open the browser console and type window. to see what's available. These utilities are stripped from production builds.

11. Deployment Rules

Golden rule: never deploy directly. All deployments happen through GitHub Actions.

Action	Branch	Result
Merge PR to `dev`	`dev`	Auto-deploys to dev environment + Firebase
Merge PR to `main`	`main`	Auto-deploys to production
Open a PR	Any branch	Preview deployment created

Commands you must never run:

bash

wrangler pages deploy   # ❌
firebase deploy         # ❌
git push origin dev     # ❌ (direct push, not via PR)
git push origin main    # ❌

CI pipeline details: docs/engineering/deployment/CICD_GUIDE.md.

12. Key Documentation Map

Use this as a navigation guide. Start with what you need right now.

Getting Started

Environment Setup — Day-one new-dev guide (5 min: npm run env:bootstrap + run the app)
Initial Project Setup (historical) — How the Firebase projects + Cloudflare Pages were originally provisioned (archived; not forward-looking)
Contributing Guidelines — Code standards and PR expectations
Security Onboarding — Security checklist for new contributors

Architecture

Scaffold & Tech Stack — Architecture rationale
Database Schema — Firestore collections in depth
Security Architecture — Security design
Zero-Knowledge Encryption — Encryption deep dive
PWA Implementation — Progressive Web App details

Daily Development

Changelog Workflow — How to write changelog entries
Console Logging — Logging conventions (no console.log in prod)
Scripts Guide — What every tooling script does
Admin Portal Setup — Setting up the admin dashboard

Deployment

Deployment Guide — Full deployment procedures
CI/CD Guide — GitHub Actions workflows
Environments — Dev/prod environment details

Features

Lantern Hub — Core check-in feature
Wave (Meeting Requests) — Wave feature
Frens — Social features
Safety — Safety & trust features

Business Context

Business Overview — Business model
Pilot Strategy — Current phase strategy
Governance — Organizational structure

13. Common Gotchas

"My changes aren't showing in Firebase" — Check VITE_APP_ENV. If it's production, you're pointing at the prod project. Use local for development.

"Tests are passing locally but failing in CI" — Run npm run validate (not just npm test). CI also runs lint and format checks that the test command alone skips.

"Coverage is below 75%" — Run npm run test:coverage to see which files are under-covered. Write tests for new functions before the PR.

"I can't log into the admin portal" — The admin password is separate from your Lantern passphrase. See Admin Authentication above.

"The app uses my real location" — Use location spoofing in dev. Set VITE_DEV_TEST_LOCATION="lat,lon" in .env.local or use the debug panel in Profile Settings → Privacy.

"ESLint is complaining about console.log" — Use console.warn or console.error instead. console.log is not allowed in production code. See docs/engineering/guides/CONSOLE_LOGGING.md.

"I accidentally pushed to dev directly" — Alert the team lead immediately. Do not try to revert on your own without guidance.

14. Your First Week Checklist

[ ] Complete environment setup and verify the dev server runs
[ ] Complete the security onboarding checklist
[ ] Read CLAUDE.md at the project root (AI assistant guidelines; also documents key conventions)
[ ] Browse docs/engineering/guides/DIRECTORY_DEFINITIONS.md to understand the docs structure
[ ] Explore apps/web/src/App.jsx to understand routing and the auth gate
[ ] Run npm run test:coverage and review what's tested
[ ] Read one completed worklog in docs/worklog/ to understand the cadence
[ ] Open your first PR (even a small docs fix counts!)
[ ] Join the incident channel and confirm you're on the on-call rotation (if applicable)

Developer Onboarding — Lantern ​

1. What Is Lantern? ​

2. Prerequisites ​

3. Repository Setup ​

Clone and Install ​

Environment File ​

Start the Dev Server ​

4. Codebase Architecture ​

Monorepo Structure ​

Web App Internals (apps/web/src/) ​

Routing ​

State Management ​

Shared Package ​

Zero-Knowledge Encryption ​

Firebase Collections ​

5. Development Workflow ​

The Git Flow ​

Before Every Commit ​

PR Rules ​

6. Key Commands Reference ​

Web App (most common) ​

Other Workspaces ​

Useful One-Offs ​

7. Security Checklist ​

Admin Authentication ​

8. Testing ​

Framework ​

Where Tests Live ​

Running Tests ​

Path Alias ​

Setup File ​

Writing Tests ​

9. Documentation Practices ​

Where Documentation Lives ​

Naming Conventions ​

Changelog ​

Documentation Types ​

10. Environments ​

Environment Detection ​

Dev Utilities ​

11. Deployment Rules ​

12. Key Documentation Map ​

Getting Started ​

Architecture ​

Daily Development ​

Deployment ​

Features ​

Business Context ​

13. Common Gotchas ​

14. Your First Week Checklist ​

See Also ​

Developer Onboarding — Lantern

1. What Is Lantern?

2. Prerequisites

3. Repository Setup

Clone and Install

Environment File

Start the Dev Server

4. Codebase Architecture

Monorepo Structure

Web App Internals (`apps/web/src/`)

Routing

State Management

Shared Package

Zero-Knowledge Encryption

Firebase Collections

5. Development Workflow

The Git Flow

Before Every Commit

PR Rules

6. Key Commands Reference

Web App (most common)

Other Workspaces

Useful One-Offs

7. Security Checklist

Admin Authentication

8. Testing

Framework

Where Tests Live

Running Tests

Path Alias

Setup File

Writing Tests

9. Documentation Practices

Where Documentation Lives

Naming Conventions

Changelog

Documentation Types

10. Environments

Environment Detection

Dev Utilities

11. Deployment Rules

12. Key Documentation Map

Getting Started

Architecture

Daily Development

Deployment

Features

Business Context

13. Common Gotchas

14. Your First Week Checklist

See Also