Civix Master Implementation Checklist

Quick Status Dashboard

APP VERSION: v3.0 (2025 USCIS Test Update)
ALGORITHM: v3.0.0 (SM-2 + 2025 Test Format)
REPO: Monorepo (apps/mobile + apps/web)
LAST UPDATED: 2026-02-14

STATUS LEGEND:
  [x] Complete
  [~] In Progress
  [ ] Not Started

2025 USCIS CIVICS TEST FORMAT

Setting	Old (2008)	New (2025)
Total questions	100	128
Questions asked	10	20
Passing score	6	12
65/20 pool	20	20
65/20 asked	10	10
65/20 passing	6	6

CURRENT SPRINT

Task	Status	Owner
Question bank (128 questions)	[x] Done	Claude
Algorithm v3.0.0	[x] Done	Claude
Docs consolidated	[x] Done	Claude
Domain + Vercel setup	[x] Done	User
Landing page (civixapp.us)	[x] Done	User
Google Search Console	[x] Done	User
Vercel API (AI Interviews)	[x] Done	Claude
Monorepo restructure	[x] Done	Claude
Deployment SOP	[x] Done	Claude
Configure env vars & deploy	[~] NEXT	User

1. CORE APP FEATURES

Quiz System

Learning Mode (immediate feedback)
Exam Mode (no feedback until end)
Difficulty levels (Easy/Medium/Hard)
Question count options (5/10/20/50/100)
Category filtering
Progress tracking
Results with score breakdown
128 questions (2025 test format)

Practice System

Mock Interview

Interview Prep Modules

2. QUESTION BANK (2025 UPDATE)

English Bank

128 official USCIS 2025 questions
20 senior (65/20) questions marked
Dynamic answer questions (President, VP, etc.)
Proper categories and tags
Difficulty levels assigned

Algorithm Updates

Languages and translations

Somali: Full 128 Q&A in Somali (apps/mobile/lib/bank/so-overlays.ts); UI and category facts in Somali.
Spanish: Full UI and category facts in Spanish; question overlays pending (EN fallback).
Farsi / Pashto: Legacy banks (FA, PS); UI and facts localized where provided.
Behavior: When user switches language, UI, questions, and US civics facts all show in the selected language.

3. OFFLINE MODE (100% Available)

Core Offline Features

Question bank bundled (128 questions)
AsyncStorage persistence
SM-2 algorithm works offline
Gamification works offline
Network status detection (expo-network)
Offline indicator component
Graceful degradation for AI features

Documentation

OFFLINE-MODE.md created

Performance (Mobile Runtime)

expo-image adopted for high-frequency profile avatars with memory/disk caching.
Tab navigation optimization: lazy: true and freezeOnBlur: true.
Zustand selector optimization in home/interview/header paths to reduce rerenders.
Performance runbook documented: docs/PERFORMANCE-RUNBOOK.md

4. WEB & INFRASTRUCTURE

Landing Page (LIVE at civixapp.us)

Instructions created (LANDING-PAGE-INSTRUCTIONS.md)
Vercel project setup
Domain configured (civixapp.us)
Page deployed and live
Google Search Console configured
Sitemap.xml generated
Security patched (Next.js v16.0.10)

Vercel API (AI Interviews)

Project structure created
OpenAI integration (GPT-4o-mini)
Rate limiting (Upstash - optional)
Device-ID authentication (no login required)
CORS via root middleware.ts (runs proxy.ts for /api/* and docs/status subdomains)
Deployment SOP created
Connect mobile app to API (wired via apps/mobile/lib/api-client.ts; set EXPO_PUBLIC_API_URL for production)
Environment variables configured
Deployed to Vercel

5. MONETIZATION

RevenueCat Integration

AdMob Integration

6. TESTING & DEPLOYMENT

Automated testing (implemented)

Web API (Vitest): Route tests for /api/health, /api/interview/start, chat, evaluate, complete in apps/web. Run: cd apps/web && npm run test. See docs/TESTING.md.
Web API smoke script: cd apps/web && npm run test:interview-api validates ordered flow (health -> start -> chat (conversation) -> evaluate (test phases) -> complete) against deployed API.
Web E2E (Playwright): Landing, GET /api/health, docs page. Run: cd apps/web && npm run test:e2e.
Mobile unit tests (Jest): lib/api-client.ts plus algorithm integrity tests (including senior evaluatable filtering and bank/ID sync). Run: cd apps/mobile && npm test.
Mobile E2E (Maestro, optional): Interview smoke flow in .maestro/flows/interview-smoke.yaml. Run: cd apps/mobile && npm run test:e2e (requires Maestro CLI + installed app).

E2E / manual (next or as needed)

Quiz flow (all modes)
Practice flow
Mock interview (all 3 modes) – Maestro smoke covers opening Mock Interview
Settings & preferences
Gamification (XP, levels, badges)

EAS Build

App Store

NEXT STEPS (Priority Order)

Landing page live (civixapp.us)
Set up Vercel API for AI interviews (code complete)
Monorepo restructure (apps/mobile + apps/web)
[~] Deploy API to Vercel - Add OPENAI_API_KEY env var (NEXT)
Connect mobile app to API (lib/api-client.ts; set EXPO_PUBLIC_API_URL for production)
Automated tests – Web Vitest + Playwright; mobile Jest (api-client) + optional Maestro. See TESTING.md.
[~] Performance profiling pass – follow PERFORMANCE-RUNBOOK.md, capture baseline traces, then decide module adoption.
Wire RevenueCat purchases
Add AdMob ads to UI
App store submission

FILE MAP (Monorepo Structure)

civix/                           # Root monorepo
├── apps/
│   ├── mobile/                  # Expo React Native app
│   │   ├── app/                 # Expo Router screens
│   │   ├── components/          # React Native components
│   │   ├── lib/
│   │   │   ├── algorithm.ts     # v3.0.0 - 2025 test format
│   │   │   ├── offline.ts       # Network status & utilities
│   │   │   ├── ai-interview.ts  # Interview modes & fallback
│   │   │   ├── bank/
│   │   │   │   └── en.ts        # 128 questions (2025)
│   │   │   └── types.ts         # QA types
│   │   ├── store/               # Zustand state
│   │   └── package.json
│   │
│   └── web/                     # Next.js webapp + API
│       ├── app/
│       │   └── api/interview/
│       │       ├── start/route.ts
│       │       ├── chat/route.ts
│       │       ├── evaluate/route.ts
│       │       └── complete/route.ts
│       ├── lib/
│       │   ├── auth.ts          # Device-ID authentication
│       │   ├── ratelimit.ts     # Upstash rate limiting
│       │   ├── openai.ts        # OpenAI client
│       │   ├── prompts.ts       # AI Officer prompts
│       │   ├── sessions.ts      # Session store
│       │   └── types.ts         # API types
│       ├── middleware.ts        # Invokes proxy (CORS on /api/*, docs/status rewrites)
│       ├── .env.example         # Environment template
│       └── package.json
│
├── docs/                        # Shared documentation
│   ├── MASTER-CHECKLIST.md      # This file - project status
│   ├── DEPLOYMENT-SOP.md        # API deployment guide
│   ├── AI-INTERVIEW-PLAN.md     # AI officer spec
│   ├── MONETIZATION-PLAN.md     # Pricing & rate limits
│   ├── OFFLINE-MODE.md          # Offline architecture
│   ├── 01-REVENUECAT-SETUP.md   # RevenueCat integration
│   ├── 02-ADMOB-SETUP.md        # AdMob integration
│   ├── 03-APP-STORE-SUBMISSION.md
│   ├── 04-GOOGLE-PLAY-SUBMISSION.md
│   ├── PRIVACY-POLICY.md        # Legal
│   └── TERMS-OF-SERVICE.md      # Legal
│
├── package.json                 # Root monorepo scripts
└── README.md                    # Getting started

QUICK COMMANDS

# From root directory:

# Install all dependencies
npm run install:all

# Start mobile app
npm run mobile:start

# Start web dev server
npm run web:dev

# From apps/mobile:
cd apps/mobile
npx expo start              # Start Expo
npx tsc --noEmit            # TypeScript check
npm test                    # Run tests
eas build --platform ios    # Build iOS

# From apps/web:
cd apps/web
npm run dev                 # Start dev server
npm run build               # Build for production
vercel --prod               # Deploy to Vercel

VERIFICATION STATUS

Check	Result
TypeScript	No errors (mobile + web)
Targeted tests	Mobile algorithm/bank: 25/25; Web interview API: 16/16
Questions	128 verified
Algorithm	v3.0.0

RECENT CHANGES (2026-02-14)

Senior algorithm + interview policy hardening

Mobile senior mode now uses evaluatable-first filtering and never falls back to non-senior pools.
Added regression tests for senior mode context handling and senior bank/ID sync.
Web interview mode policy is centralized in apps/web/lib/interview/mode-policy.ts.
/api/interview/evaluate is now phase-locked (OUT_OF_ORDER on mismatched type/phase), and civics uses server-issued active question + answer token to prevent out-of-sequence scoring.
Added route tests for 55/15 exemption behavior and evaluate endpoint coverage.

Mobile performance pass

Switched repeated avatar images to expo-image with memory+disk caching.
Added tab lazy loading + freezeOnBlur.
Replaced whole-store subscriptions with selected Zustand slices in hot screens/components.
Added docs/PERFORMANCE-RUNBOOK.md with profiling workflow and native module adoption roadmap.

API and CORS

Root middleware.ts added: runs proxy.ts so CORS is applied to /api/* for browser-origin requests; docs/status subdomain rewrites unchanged.
Checklist: "Connect mobile app to API" and CORS via middleware marked done; verification script npm run verify-api in apps/web for post-deploy health check.

API Implementation

Created Interview API endpoints (/api/interview/*)
OpenAI GPT-4o-mini integration for AI Officer
Device-ID based auth (no user sign-in required)
Rate limiting with Upstash Redis (optional)
CORS middleware for mobile app access

Monorepo Restructure

Moved mobile app to apps/mobile/
Moved web app to apps/web/
Removed legacy CIVICS-af/ folder
Removed nested .git from web
Created root package.json with workspace scripts
Created README.md with setup instructions

Documentation

Created DEPLOYMENT-SOP.md - step-by-step deploy guide
Updated all docs with new monorepo paths
Simplified auth (no JWT needed)
Algorithm: Added ALGORITHM-REPORT.md (version, mastery levels, study modes, priority factors, constants, optimization status). Algorithm fixes: MasteryProgress.learning no longer double-counts with due/overdue; weightedShuffle optimized. New tests: MasteryProgress counts, review-mode due-only selection, coverage-mode unseen inclusion, exam senior 10 questions. See TESTING.md for algorithm test coverage.

Last updated: 2026-02-14