An offline-first Progressive Web App (PWA) for AFOQT preparation with retro terminal UI, RPG mechanics, and procedurally generated + content-based questions.

# Serve locally
python3 -m http.server 8000

# Open in browser
open http://localhost:8000

Play AFOQT Quest →

Note: After updates, hard refresh (Ctrl+Shift+R / Cmd+Shift+R) to clear service worker cache.

→ Full Test Sites Guide — Complete reference for all 20+ testing utilities

• Adding Content? → Test at: Content Loader → All Questions Browser → Main App
• CSS Broken? → Check at: CSS Verification → Subject Test → Main App
• Questions Not Loading? → Diagnose with: Content Loader → Console (F12) → patch-loader.js review
• Bootstrap Issues? → Debug at: Boot Demo → App.js Error Check → Browser Console

• Hard refresh browser (Ctrl+Shift+R / Cmd+Shift+R) after updates to clear service worker cache
• If a test shows 404 for JSON files, check that paths use /AFOQT-app/Test Content/...
• Service Worker cache version is v110 — increment if pushing JS/CSS changes
• All test pages work on GitHub Pages with absolute paths

• ✅ Offline-First PWA: Works without internet after first load
• ✅ Retro Terminal UI: Cyberpunk aesthetic with CRT scanlines and matrix rain
• ✅ RPG Progression: Level up with XP, stats (Strength, Wisdom, Speed), achievements
• ✅ Multi-Player Support: Create multiple player profiles with separate progress
• ✅ Session Persistence: Auto-save to localStorage, resume interrupted sessions

• ✅ 2,200+ Official AFOQT Questions (Patches 18-22)
• ✅ Content-Based System: JSON-driven questions with rich metadata
• ✅ 6 Official AFOQT Subjects:
  • Word Knowledge (Synonyms, Antonyms, Context Clues)
  • Arithmetic Reasoning (Word Problems, Algebra, Ratios)
  • Reading Comprehension (Passages with clustered questions)
  • Math Knowledge (27 topics: Algebra, Geometry, Trig, etc.)
  • Instrument Comprehension (Aircraft attitude/heading from instruments)
  • Table Reading (X/Y coordinate lookup with speed emphasis)
• ✅ Practice Test Mode: AFOQT-realistic simulations (no feedback until completion)
• ✅ Study Mode: Immediate feedback with explanations, fast strategies, step-by-step solutions

• ✅ Math UI: 20+ specialized renderers (coordinate graphs, transformations, geometry diagrams)
• ✅ Reading Comprehension: Passage blocks with clustered questions
• ✅ Instrument Panel: Attitude indicator, compass, aircraft silhouettes (SVG)
• ✅ Data Tables: X/Y axis clarity with column/row headers
• ✅ LaTeX Math: KaTeX support for equations

• ✅ Spaced Repetition: Smart question selection via IndexedDB
• ✅ Performance Analytics: Track progress by subject/subtopic/difficulty
• ✅ Difficulty Modes: Beginner (1x XP), Advanced (1.5x), Expert (2x)
• ✅ Theme System: 8+ color schemes (Tron, EVA-01, RX-0, Stealth, Terminal Green, etc.)
• ✅ Audio Effects: Web Audio API beeps (correct, wrong, levelup, navigation)

• 50 beginner questions (25 per part) with shared tableSpec
• renderDataTable() with X/Y axis legend and labeled headers
• AFOQT Table Reading Practice Test (40 questions, 40/40/20 difficulty mix)
• Subject ID standardized to table_reading

• 10 beginner questions with instrument_panel uiSpec
• renderInstrumentPanel(): Attitude indicator (bank/pitch) + Compass (heading)
• renderInstrumentChoiceSprite(): Realistic SVG aircraft silhouettes (side/front view)
• AFOQT Instrument Comprehension Practice Test (25 questions, 35/45/20 mix)
• Aircraft sprites match AFOQT exam style (grayscale, professional diagrams)

• 20 beginner passages with 3-5 questions each
• rc_passage_block and rc_question_block renderers
• AFOQT Reading Comprehension Practice Test (20 questions)
• Passage clustering for realistic test experience

• 350+ questions across 8 subtopics (19 JSON files)
• Topics: Basic Arithmetic, Word Problems, Fractions/Decimals, Percents, Ratios, Time/Rate/Work, Averages, Algebra
• AFOQT Arithmetic Reasoning Practice Test (50 questions)
• Dynamic topic generation from questionRegistry

• 1,614 questions: 814 vocabulary + 800 math knowledge
• 27 math topics with specialized UI renderers
• AFOQT Word Knowledge Practice Test (40 questions)
• AFOQT Math Knowledge Practice Test (50 questions)

AFOQT-app/
├── Frontend/                      # Deployed site content (served on GitHub Pages)
│   ├── index.html                 # App entry
│   ├── app.js                     # Core app logic (10k+ lines)
│   ├── styles.css                 # Theme + UI
│   ├── manifest.json              # PWA manifest
│   ├── sw.js                      # Service worker (cache v111)
│   ├── patch-loader.js            # Patch system & question registry
│   ├── db.js                      # IndexedDB helpers
│   ├── assets/                    # Icons, libs, scripts
│   ├── Test Content/              # JSON question banks (runtime)
│   └── tests/                     # Admin + diagnostics pages
├── Backend/                       # Tools, scripts, developer docs
│   ├── tools/                     # CLI utilities
│   ├── docs/                      # Technical documentation
│   ├── *.py                       # Content processing scripts
│   └── *.md                       # Analysis/status reports
├── .github/workflows/deploy-pages.yml  # Pages deploy pipeline (Frontend → Pages)
├── .nojekyll
└── README.md

• GitHub Pages is configured via Actions to deploy the Frontend/ folder.
• Project page URL: https://swolem12.github.io/AFOQT-app/
• After updates: force refresh to clear Service Worker.

• Levels: Gain XP from answering questions (difficulty multipliers apply)
• Stats: Strength (Math/Science), Wisdom (Verbal/Reading), Speed (Table Reading)
• Achievements: Unlock badges for milestones (100 questions, 10 sessions, perfect scores)

1. Practice Mode (Study):

   • 10 questions, immediate feedback
   • Explanations, fast strategies, step-by-step solutions
   • XP multiplier based on difficulty (1x/1.5x/2x)

2. Test Mode (Simulation):

   • 10 questions, no feedback until completion
   • Simulates test-taking conditions
   • 1.5x XP bonus

3. Sprint Mode:

   • 5 questions, mixed difficulties
   • Fast-paced practice

4. Practice Test Mode (AFOQT Official):

   • 20-50 questions (subject-dependent)
   • No feedback until end
   • Summary report with analytics (score, breakdowns, missed questions)
   • Realistic AFOQT test experience

All practice experiences randomize questions to avoid repetition while respecting mode rules:

• Registry Selection: getQuestionsFromRegistry() shuffles pools and samples up to the requested count per subtopic/difficulty.
• Spaced Repetition: getQuestionsWithSpacedRepetition() prioritizes due items, fills with unseen, then random seen items; each bucket is shuffled.
• Practice Tests (AFOQT): generateAfoqtPracticeTest() performs stratified random sampling according to configured difficultyDistribution, then shuffles to exact length.
• Sprint Mode: Mixes difficulties and shuffles before slicing to size.
• Procedural Fallbacks: Generators construct unique sets and use shuffled choices per item.

Result: Every run provides a varied order and selection across study, sprint, and practice test modes.

• Single-Page App: No build step, vanilla JavaScript
• Monolithic Design: app.js contains all logic (screens, rendering, state, events)
• Global State: Single state object (lines 320-355 in app.js)
• localStorage: Player profiles, session data
• IndexedDB: Question history for spaced repetition (db.js)

• Registry Structure: questionRegistry[subjectId][subtopicId][difficulty] = Question[]
• JSON Schema: {id, question, choices: {A,B,C,D}, answer, explanation, uiSpec}
• Dynamic Loading: Patch-based system scans for <subtopicId>_<difficulty>_part<N>.json files
• Topic Generation: create<Subject>TopicsFromRegistry() functions build topic lists

• Math UI: CSS-based graphs (no Canvas/SVG for performance)
  • Coordinate grids, transformations, geometry diagrams
  • renderMathUI(uiSpec) dispatcher with 20+ renderers
• Instrument Comprehension: SVG aircraft with rotation/bank transforms
• Table Reading: HTML tables with X/Y axis headers
• Reading Comprehension: Styled passage blocks + question blocks

• Service Worker: Cache-first strategy (v75)
• Offline Support: All core assets cached
• Installable: Add to home screen on mobile/desktop
• Manifest: display: standalone, tron theme color (#00ffff)

8 built-in themes accessible via Settings → Theme:

• Tron (default): Cyan (#00ffff) with CRT scanlines
• EVA-01: Purple/green (Evangelion-inspired)
• RX-0: White/gold (Gundam Unicorn)
• Sinanju: Red/gold
• Stealth Black: Grayscale minimalist
• Terminal Green: Classic green terminal
• Dracula: Purple/pink
• Nord: Blue/frost

Web Audio API with frequency modulation:

• Correct: 800Hz beep
• Wrong: 200Hz buzz
• Level Up: Ascending arpeggio
• Navigation: 400Hz click
• Separate volume controls per effect type

• Word Knowledge: 40 questions
• Math Knowledge: 50 questions
• Arithmetic Reasoning: 50 questions
• Reading Comprehension: 20 questions
• Instrument Comprehension: 25 questions
• Table Reading: 40 questions

• Advanced/Expert questions for Patches 19-22
• Science Reasoning questions (official AFOQT subject)
• Aviation Information questions
• Block Counting (spatial reasoning)
• Full-length AFOQT simulation (all subjects combined)

• Study streaks and daily goals
• Leaderboards (Firebase integration)
• Question bookmarking/favorites
• Custom quiz builder
• Performance charts (Chart.js)
• Export session reports (PDF)

• TypeScript migration
• React/Next.js refactor (optional)
• Question search/filter
• Keyboard shortcuts
• Mobile gesture controls
• Dark mode improvements

1. Create JSON file in Test Content/<Subject>/
2. Follow naming: <subtopicId>_<difficulty>_part<N>.json
3. Schema: {subjectId, subtopicId, difficulty, part, questions: [...]}
4. Each question: {id, question, choices: {A,B,C,D}, answer, explanation, [uiSpec], [steps], [fastStrategy]}
5. Test with tests/test-real-questions.html

1. Add uiSpec.type to question JSON
2. Create render<Type>() function in app.js
3. Add case to renderMathUI() switch
4. Style with inline CSS (retro terminal theme)

• Each patch = thematic content addition
• Patch config JSON defines schema, rules, acceptance criteria
• Loaders in patch-loader.js populate questionRegistry
• Topic creators in app.js generate topic arrays from registry

MIT License - Free to use, modify, and distribute.

• Developer: @swolem12
• Inspired by: AFOQT study guides, retro terminal aesthetics, RPG progression systems
• Libraries: anime.js (animations), KaTeX (math rendering)
• Icons: Custom maskable icons for PWA

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Last Updated: December 6, 2024
Version: Patch 22 (v75)
Questions: 2,200+ across 6 official AFOQT subjects