Lantern

Appearance

Tech Stack — lantern_app 💡 ​

Summary ​

This project will use a Google / Firebase + GCP-first stack focused on fast time-to-market, strong security defaults, and excellent PWA support. The list below explains what each technology is and what it does for the app.

What is a PWA? 📱 ​

Progressive Web App (PWA) is a set of best practices and technologies that make web apps behave like native apps: installable to the home screen, load reliably and fast, work offline, and support push notifications. Core pieces:

  • Service Worker — background script that enables offline caching, request interception, and push handling.
  • Web App Manifest — JSON file (you already have manifest.webmanifest) that describes the app (name, icons, theme) and enables installability.
  • HTTPS and secure contexts — required for installability and service workers.

Core stack (what we will use and why) ✅ ​

Frontend ​

  • React + Vite — fast development, fast builds, and good PWA integration. (Already in repo)
  • TypeScript (recommended) — type safety and better developer experience.
  • vite-plugin-pwa — integrates service worker generation and caching strategies with Vite.

Authentication & Identity ​

  • Firebase Authentication — managed auth (email/password, OAuth providers, phone, multi-factor). Simplifies secure sign-in flows and integrates with other Firebase services.

Database & Offline ​

  • Cloud Firestore (Firebase) — document database with real-time sync and built-in offline persistence for web PWAs. Use it for user data and app state that benefits from realtime updates.

Storage ​

  • Firebase Storage (backed by GCS) — file uploads & user-generated content with secure rules and signed URL support.

Hosting & CDN ​

  • Firebase Hosting — global CDN optimized for static PWAs; works seamlessly with firebase deploy and serves the service worker & manifest correctly.

Serverless / Business Logic ​

  • Cloud Functions for Firebase (or GCP Cloud Functions / Cloud Run) — server-side logic, webhook handlers, scheduled jobs, and secure token verification.

Messaging & Notifications ​

  • Firebase Cloud Messaging (FCM) — web push notifications and mobile push integration.

Observability & Security ​

  • Cloud Logging / Cloud Monitoring — logs and metrics for backend services.
  • Sentry (optional) — frontend & server error tracking and release alerts.
  • Cloud IAM & Secret Manager — manage service account permissions and store secrets securely.

CI/CD & Quality ​

  • GitHub Actions — CI for lint/test/build and firebase deployment jobs.
  • Lighthouse CI — automated PWA/performance audits in CI.

Security & hardening highlights 🔒 ​

  • App Check — prevent abuse of backend resources by attesting legitimate clients.
  • Firestore Security Rules — deny-by-default rules and per-document access control.
  • MFA & secure auth flows — require MFA for sensitive accounts (admins).
  • Short-lived credentials & Secret Manager — rotate secrets and avoid embedding service account keys in the repo.
  • HTTPS, CSP, HSTS, SRI — protect clients and reduce XSS/CSRF risk.
  • Firebase Emulator Suite — local testing for Auth, Firestore, Functions, Storage and rules.

See ../governance/SECURITY.md for a full security checklist, threat model, incident response plan, and compliance roadmap.

For database scaling strategy, migration triggers, and cost optimization, see DATABASE_SCALING.md.

Practical setup steps (next actions) ▶️ ​

  1. Create a Firebase project and enable: Authentication, Firestore, Hosting, Storage, Functions, and App Check.
  2. Add Firebase config to your app via environment variables (do not commit keys). Example: VITE_FIREBASE_API_KEY etc.
  3. Install SDKs and plugins:
    • npm install firebase
    • npm install -D vite-plugin-pwa
  4. Add vite-plugin-pwa config and a service worker strategy (e.g., network-first for API & cache-first for static assets).
  5. Write basic Firestore Security Rules and test them with the Emulator.
  6. Add GitHub Actions: lint → test → build → Lighthouse → firebase deploy (for hosting + functions).

Mobile roadmap (React Native) 📱 ​

We plan to add Android and iOS apps using React Native after we validate the web PWA design. Key notes:

  • Strategy: Start with a single codebase (React + React Native) and maximize code sharing using React Native for Web or a monorepo (e.g., Turborepo / pnpm workspaces).
  • Build tools: Use Expo + EAS for fast native builds and OTA updates, or React Native CLI + Fastlane for more control.
  • Firebase on mobile: Use react-native-firebase (native SDKs) for Auth, Firestore, Storage, FCM, and Crashlytics; this provides better native integration than the web SDK.
  • Push & notifications: Configure FCM with native Android/iOS setup and handle native permission flows.
  • Security & attestation: Use device attestation (Play Integrity / Apple DeviceCheck / App Attest) and server-side protections for critical operations; note App Check is web-focused.
  • Testing & rollout: Use TestFlight / Google Play internal tracks and staged rollouts; add E2E mobile tests (Detox / Appium) and CI build pipelines.

PWA-first helps validate UX and offline behavior before investing in native builds.

Files / changes I can add in a starter PR 🛠️ ​

  • TECHSTACK.md (this file)
  • firebase directory with example firestore.rules, storage.rules, and firebase.json for Hosting and Functions.
  • vite.config.ts changes to add vite-plugin-pwa sample config.
  • Example src/firebase.ts showing how to initialize Firebase with VITE_ env vars and enable Firestore offline persistence.
  • CI workflow file (.github/workflows/ci.yml) that includes Lighthouse CI and a firebase deploy job (secrets set via GitHub).

Notes & tradeoffs ​

  • Using Firebase/GCP gives strong managed security and fast time-to-market, but consider data residency and costs as reads/writes scale.
  • For complex relational queries, use a hybrid approach (e.g., Cloud SQL + Cloud Run) later if needed.

If you'd like, I can open a starter PR that adds the Firebase config examples, PWA plugin integration, and a CI job. Which of the starter PR items above should I include first?

For governance & security guidance, see ../governance/GOVERNANCE.md and ../governance/SECURITY.md in the repository for recommended legal protections and a security-first checklist.

Built with VitePress

Copyright © 2026 Lantern