Architecture & Technical Reference
This document provides a technical overview of the Scripture Habit architecture, detailing the technology stack, directory structure, data flow, and state management strategy.
TIP
Interactive Architecture Tour: Open Live Tour (App Bootstrapping & Routing)
1. Tech Stack
Built on modern web standards to deliver high responsiveness and a cohesive developer experience.
| Layer | Technology | Rationale & Responsibility |
|---|---|---|
| Frontend | React 19 + Vite 8 | Fast builds and modern component architecture |
| Routing | React Router 7 | SPA navigation and deep-link routing |
| State & Data Fetching | Zustand 5 / TanStack Query 5 | Lightweight UI state and efficient API cache management |
| Real-Time Data | Firebase Client SDK 12 | Firestore WebSocket listeners for instant message synchronization |
| Backend API | Node.js >= 22 (LTS 24) + Express 5 | Robust serverless API gateway hosted on Vercel Functions |
| Database | Cloud Firestore | Real-time, document-oriented NoSQL database |
| Authentication | Firebase Authentication | Secure sign-in (Google / Email) and server-side JWT verification |
| AI Subsystem | Gemini 3.1 Flash-Lite | Multilingual translation, question prompts, and reflection letters |
2. Directory Structure & Responsibilities
Maintains clear separation of concerns with predictable module boundaries.
scripture-habit/
├── api/ # Vercel Serverless Function entry points
├── api_internal/ # Core backend logic (routes, services, notifications, cron)
├── backend/ # Local development Express server wrapper (Port: 5000)
├── src/ # Frontend client (React 19 + Vite application)
└── types/ # Shared TypeScript schemas and data contracts3. System Component Architecture
To maintain clarity and legibility in Markdown previewers, the architecture is presented in three focused views with balanced aspect ratios:
- High-Level Overview: Core interactions across Frontend, Backend, and Cloud Platform.
- Frontend & Workflows: Component orchestration, custom hooks, and state boundaries.
- Backend & Platform Services: Serverless API routes, domain services, and external integrations.
3.1 High-Level Architecture Overview
A balanced top-to-bottom overview showing user flows from the React PWA client through trusted API gateways and real-time Firestore synchronization.
NOTE
Architectural Rationale: See ADR-001: CQRS Architecture for why client writes are locked down and all state mutations run inside privileged backend transactions.
3.2 Frontend Client & Feature Workflows
Detailed component composition, state management, study workflows, and offline-capable chat queues.
NOTE
Design Decisions:
- Logic-Component Split: See ADR-002 for our strict rule that components only render UI while custom hooks manage all effects and state.
- Offline Strategy: See ADR-003 for why we use user-scoped application queues instead of Workbox BackgroundSync.
- Multilingual Rendering: See ADR-004 for our hybrid static dictionary and on-demand AI translation strategy.
- Milestone Psychology: See ADR-005 for the psychological rationale behind cumulative study days without zero-resets.
3.3 Backend API & Cloud Infrastructure
The trusted server-side execution path, flowing downwards from triggers to Express pipeline, domain services, Firestore transactions, and Gemini AI.
4. Layer Architecture & State Taxonomy
① Logic-Component Split
- UI Components (
src/components/): Dedicated to layout, styling (Vanilla CSS), and visual presentation. - Custom Hooks (
src/hooks/): Handle server communication, data synchronization, and business logic.
② State Management Division
- Real-Time Data (Chat, Unread Counts, Streaks): Subscribed via Firestore
onSnapshotfor instant updates. - Server API State (System Settings, Static Metadata): Managed and revalidated through TanStack Query.
- Global UI State (Modals, Theme): Maintained in lightweight Zustand stores.
- Auth State: Centrally managed through
AuthContext.
5. Data Flow: Decoupled Writes and Real-Time Subscriptions
Scripture Habit adopts a data flow architecture that cleanly separates transactional write operations from real-time subscriptions.
Data Flow Mechanism
Write Operations (Mutations)
When a user creates a study note or sends a chat message, the frontend custom hook dispatches a request to the backend API.
The server verifies authentication via JWT and validates the payload using Zod schemas. It then executes a Firestore atomic transaction to calculate study metrics, synchronize chat feeds, and update progression levels simultaneously.Real-Time Synchronization (Subscriptions)
Upon database updates, FirestoreonSnapshotlisteners deliver changes directly to the client without requiring page reloads.
This instantly updates both the user's own actions and activities from group members, such as new study notes and shared Unity progress.Separation of Writes and Reads
Executing writes through backend API transactions while streaming updates through real-time subscriptions prevents client-side state divergence and guarantees strict data consistency across devices.