Skip to content

README.md

Latest commit

 

History

History
165 lines (119 loc) · 5.43 KB

README.md

File metadata and controls

165 lines (119 loc) · 5.43 KB
Raw

Open Ham Prep

Website App GitHub branch status codecov GitHub last commit (branch) GitHub License

A modern web application for studying US Amateur Radio license exams. Open source, community-driven, born in North Carolina.

Live App: app.openhamprep.com

Features

  • Practice Tests - Simulated exam experience with optional timer
  • Random Practice - Study questions with instant feedback
  • Study by Topics - Focus on specific subelements with topic mastery quizzes
  • Lessons - Curated, guided study units
  • ARRL Chapters - Practice scoped to ARRL study-book chapters
  • Weak Questions - Review questions you've missed
  • Glossary & Flashcards - Learn key terms with spaced repetition
  • Exam Sessions - Find upcoming in-person VE exam sessions near you
  • Ham Radio Tools - Curated gallery of external ham radio tools
  • Progress Tracking - Dashboard with test readiness, streaks, and goals
  • Bookmarks - Save questions with personal notes
  • Guest Mode + PWA - Study without an account; installable as a Progressive Web App

Supports all three license classes: Technician, General, and Extra.

Quick Start

Prerequisites: Node.js 20+, Docker Desktop

git clone https://github.com/sonyccd/openhamprep.git
cd openhamprep
npm install
npm run dev:full

See LOCAL_DEVELOPMENT.md for details.

Tech Stack

Frontend: React 18, TypeScript, Vite, Tailwind CSS, shadcn/ui, TanStack Query, Framer Motion

Backend: Supabase (PostgreSQL, Auth, Edge Functions, Realtime)

Tooling: Vitest, ESLint, Amplitude & Pendo (product analytics), Sentry (error tracking), Vercel Analytics & Speed Insights

Architecture

Core Data Flow

  1. Global License Context - App-wide filter (Technician/General/Extra) via useAppNavigation
  2. Authentication - Supabase Auth via useAuth context
  3. Data Fetching - TanStack Query with custom hooks in src/hooks/
  4. Progress Tracking - User attempts saved per-question for analytics

Context Providers

The app wraps components in this provider order, outermost → innermost (see App.tsx):

  1. ThemeProvider (next-themes)
  2. AccessibilityProvider (a11y prefs)
  3. QueryClientProvider (TanStack Query)
  4. AuthProvider (Supabase auth — gates user-scoped queries)
  5. PendoProvider + AmplitudeProvider (product analytics)
  6. AppNavigationProvider (global license filter)
  7. TooltipProvider (Radix)

Project Structure

src/
├── components/      # React components
│   ├── ui/          # Base shadcn components
│   ├── admin/       # Admin-only components
│   └── *.tsx        # Feature components
├── hooks/           # Custom React hooks
├── pages/           # Route page components
├── services/        # Service layer + centralized query keys
├── lib/             # Utilities
├── integrations/    # Supabase client (auto-generated)
├── assets/          # Static assets
├── test/            # Test setup and helpers
└── types/           # TypeScript types

Design System

Important: Never use direct colors. Always use semantic tokens:

// Correct - works in light/dark mode
<div className="bg-background text-foreground">

// Wrong - breaks theme switching
<div className="bg-white text-black">

Available tokens: background, foreground, card, primary, secondary, muted, accent, destructive, success, border

See src/index.css for all token definitions.

Commands

npm run dev              # Start dev server
npm run dev:full         # Start Supabase + dev server
npm run supabase:stop    # Stop Supabase
npm run supabase:reset   # Reset database
npm test                 # Run tests
npm run build            # Production build

Environment Setup

Local Development (Recommended)

Uses local Supabase via Docker - no hosted account needed:

npm run dev:full    # Start Supabase + dev server

Hosted Supabase

For production or if you have Supabase project access:

cp .env.example .env.local
# Edit .env.local with your credentials
npm run dev

Documentation

Contributing

  1. Fork the repo
  2. Run locally with npm install && npm run dev:full
  3. Make your changes
  4. Submit a pull request

See CONTRIBUTING.md for guidelines.

License

© Brad Bazemore

Support

  • File issues on GitHub
  • Visit ARRL.org for ham radio learning resources