Civics Check

America's 250th civics fair — offline quizzes, pavilion browsing, and the USCIS naturalization test bank. Pure Python; no accounts, no network required after install.

Runs on its own. You do not need the SAFE App Store monorepo — copy this directory anywhere, or install with pip.

Install (standalone)

From this directory (apps/civics-check in the monorepo, or a copy of that folder):

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .
civics-check                       # console script → app.py

Or use the launcher (creates ~/.willow/apps/civics-check/.venv automatically):

./dev.sh                           # fair TUI (default)
./dev.sh --cli                     # stdlib fair map only

Run (standalone)

Rebuild catalog after editing sources:

python3 scripts/build_catalog.py

Monorepo (optional)

If you have the full safe-app-store checkout:

make install app=civics-check
make run app=civics-check          # runs app.py in apps/civics-check

What you get

• Fair map — parchment lanes (Citizenship Court, Statehouse Row, Founders Hall, …) with pavilion tents
• Naturalization quiz — 10 questions, 6 of 10 to pass (same rule as USCIS civics)
• Speed round — 60 seconds against the full bank
• State matchups — capitals and admission order
• Timeline sort, quote match, colonies flashcards, amendment explorer, and more
• Local progress — missed-question tracking and scores in civics_check.db (dev tree) or ~/.willow/apps/civics-check/ (pip install)

Keyboard (TUI)

Data workflow

Never hand-edit data/catalog.json. It is compiled output.

1. Edit JSON under data/sources/ (questions, presidents, numbers, links, fair schedule, …)
2. Rebuild: python3 scripts/build_catalog.py
3. Test: python3 -m unittest discover -s tests -v

Project layout

app.py              Primary entry (SAFE) — TUI when Textual present, else fair CLI
tui.py              Textual fair map + stage (optional direct launch)
tui_art.py          Hero band, curtains, ASCII ceremony
engine.py           Catalog facade shared by CLI and TUI
bell.py             Liberty Bell narrator + Joan Stark banner art
db.py               Local SQLite scores / missed questions
civics/
  catalog.py        Load compiled catalog
  paths.py          Resolve app root + data/ (dev, editable, wheel)
  scoring.py        Answer matching
  session.py        Activity state machine
scripts/
  build_catalog.py  Compile sources → catalog.json
data/
  sources/          Authoritative JSON (edit these)
  catalog.json      Generated — do not edit
tests/
dev.sh              Standalone launcher (venv + catalog + run)
pyproject.toml      pip install -e . / civics-check console script
safe-app-manifest.json

SAFE manifest

Registered as civics-check in the SAFE App Store monorepo (entry_point: app.py). Permissions: file_write for local SQLite only.

License

MIT — see LICENSE.

ΔΣ=42