Civix Documentation

This folder contains the operational and engineering documentation for the Civix monorepo.

Canonical Docs (Start Here)

• docs/MASTER-CHECKLIST.md: current project status and release priorities.
• docs/ALGORITHM-REPORT.md: source-of-truth behavior for apps/mobile/lib/algorithm.ts.
• docs/TESTING.md: automated test coverage and commands.
• docs/DEPLOYMENT-SOP.md: API deployment and environment setup.
• docs/08-PRODUCTION-READINESS.md: release readiness gates.
• docs/PERFORMANCE-RUNBOOK.md: mobile performance profiling checklist, acceptance targets, and native module adoption roadmap.

Architecture Summary

• apps/mobile: Expo/React Native app with offline-first question bank and SM-2 learning.
• apps/web: Next.js app with landing pages and Interview API.
• Interview API routes:
  • POST /api/interview/start
  • POST /api/interview/chat
  • POST /api/interview/evaluate
  • POST /api/interview/complete

Interview API Notes

Current behavior is centralized and mode-consistent:

• standard: 20 civics, pass at 12, English tests required.
• 65_20: exemption mode, 10 civics, pass at 6, English tests waived.
• 55_15: exemption mode, 10 civics, pass at 6, English tests waived.

Evaluation uses the full 128-question bank in web (apps/web/lib/interview/civics-bank.ts). Interview flow is ordered and timed:

• Conversational phases use POST /api/interview/chat.
• Test phases use POST /api/interview/evaluate.
• Civics evaluation is server-ordered using activeCivicsQuestion.questionId + answerToken; out-of-order attempts return OUT_OF_ORDER.

Documentation Hygiene

When implementation changes, update at least these files in the same PR:

1. docs/ALGORITHM-REPORT.md for algorithm behavior changes.
2. docs/TESTING.md for new/changed tests.
3. docs/MASTER-CHECKLIST.md for status/roadmap shifts.
4. docs/DEPLOYMENT-SOP.md when env vars, infra, or API behavior changes.