Architecture

Architecture Guide — CIVICS-af

Overview

CIVICS-af is a multilingual mobile app for U.S. Civics Test preparation. The system is built with React Native (Expo) and designed for maintainability, scalability, and accessibility. This document describes the overall architecture, file organization, data flow, and key design decisions.

Core Architecture

  • Framework: React Native (Expo SDK 52+)
  • Navigation: Expo Router with file-based routing
  • State Management: Zustand (useAppStore) with persistence
  • Theming: Custom hook useTheme supporting dark/light modes
  • i18n: Simple key-based translations, language picker modal
  • Data Storage: AsyncStorage (via Zustand persist middleware)

File Organization

app/
 ├── index.tsx          # Home screen
 ├── quiz/              # Quiz module
 ├── practice/          # Practice module
 ├── favorites/         # Favorites module
components/
 ├── AppText.tsx        # Typography component
 ├── AppButton.tsx      # Button component
 ├── ThemeBackground.tsx# Background + theme layer
 ├── LanguagePicker.tsx # Modal picker for languages
 ├── NameSetupModal.tsx # (new) Name collection modal
lib/
 ├── i18n.ts            # Translation utilities
 ├── theme.ts           # Theme system
store/
 ├── useAppStore.ts     # Zustand store (lang, name, access)
assets/
 └── images/flag1.jpg

Data Flow

  1. User state is managed in useAppStore.
    • lang — Current language
    • name — User’s saved name
    • hasAccess() — Premium access check
  2. Home screen (index.tsx) pulls state and renders greeting, language picker, and navigation buttons.
  3. Navigation routes users to Quiz, Practice, and Favorites modules.
  4. Name Setup Modal ensures personalization data (name) is collected and persisted.

Component Interaction

  • AppText / AppButton → Common styled primitives
  • ThemeBackground → Handles background image, blur, gradient
  • LanguagePicker → Modal overlay triggered from Home
  • NameSetupModal → Blocks navigation until name is provided

Future Architecture Considerations

  • Move from local storage to remote backend (e.g., Supabase or Firebase) for syncing progress.
  • Add analytics layer for tracking practice performance.
  • Introduce modular feature flags for paywall vs. free content.
  • Expand i18n infrastructure for auto-detecting device locale.

Last updated: September 2025