Skip to content

CLAUDE.md

Latest commit

 

History

History
112 lines (83 loc) · 4.6 KB

CLAUDE.md

File metadata and controls

112 lines (83 loc) · 4.6 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Hamlearn is a web-based ham radio license exam practice application supporting Technician and General class exams. The application is a client-side JavaScript application with no build process - all files are served statically.

Development Commands

Local Development Server

python3 -m http.server 8000

Run in repository root to serve files at http://localhost:8000/. Required for fetch requests to work properly.

Testing

No automated tests - use manual testing:

  • Complete full 35-question exam cycle
  • Test navigation (Previous/Next buttons)
  • Verify figure display and hints
  • Test submission and score report
  • Validate score calculations with various answer combinations
  • Test "remove image questions" toggle functionality

Architecture

Core Components

HTML Files:

  • index.html - Entry point linking to license class options
  • technician.html - Main exam UI with embedded CSS and initialization scripts

JavaScript Modules (loaded in order):

  • app-utils.js - Utility functions for question parsing and exam generation
  • pool.js - Question pool loader with fetch-based loading and caching
  • exam-app.js - Main exam application framework
  • exams.js - Exam registry that configures Technician and General exams

Data Flow

  1. Initialization: URL query parameters determine exam type (technician or general)
  2. Pool Loading: Questions loaded from plain text files via fetch API
  3. Exam Generation: One question randomly selected from each group (35 groups total)
  4. Question Filtering: Optional removal of image-based questions for accessibility

Key Design Patterns

Modular Architecture: Each JavaScript file exposes a global API object:

  • window.HAMLEARN_UTILS (app-utils.js)
  • window.HAMLEARN_POOL (pool.js)
  • window.createExamApp (exam-app.js)
  • window.HAMLEARN_EXAMS (exams.js)

Question Pool Structure: Questions organized by subelement groups (e.g., T1A, T1B, etc.) with exactly one question selected per group per exam.

Figure Management: Images (T1, T2, T3 for Technician; G7-1 for General) automatically detected from question text and displayed when referenced.

File Organization

Question Data

  • Technician Pool.txt - FCC Technician class question pool (plain text format)
  • General pool.txt - FCC General class question pool (plain text format)
  • t1.jpg, t2.jpg, t3.jpg - Technician exam figures
  • G7.png - General exam figure

Configuration

Question format: ID (CORRECT_ANSWER) [REFERENCE] followed by question text and A-D choices.

Code Style Guidelines

  • HTML: 2-space indentation, semantic tags preferred
  • CSS: Use existing custom properties on :root, utility-style classes preferred over inline styles
  • JavaScript: Use const/let, arrow functions for callbacks, descriptive helper names (e.g., renderReport, clearReport)
  • Security: Always use escapeHTML() utility before DOM injection to prevent XSS

Commit Guidelines

  • Use conventional succinct commit messages with imperative verb + scope (e.g., "Add score report table")
  • Reference related issues in commit body when applicable
  • For UI updates, include screenshots or GIFs in pull requests
  • When updating FCC question pools, note the effective date and call out data changes
  • Keep unused assets out of repository to maintain lightweight distribution

Question Pool Management

Plain Text Structure

Each question follows this format:

[subelement][group][questionNum] [correct answer] [FCC rule (optional)]

Example: T1A01 (C) [97.1]

Pool Organization

  • Technician: 35 groups across 10 subelements (T1-T0), 1 question per group
  • General: Same structure but 37/50 questions needed to pass (74%)
  • Questions distributed among subelements with unique group identifiers
  • Maintain unique question IDs to prevent duplicates

Exam Generation Logic

The exam builder (buildExamRun in app-utils.js) ensures:

  • Exactly one question selected from each group
  • Groups are shuffled to prevent predictable question order
  • Figure filtering works at the group level when "remove image questions" is enabled

Important Notes

  • No build process required - files served directly as static content
  • Application works offline once loaded (questions embedded in JS)
  • Question pools must maintain exact group structure for proper exam generation
  • Opening technician.html directly from disk works because question pool is embedded
  • When FCC releases pool revisions, update JS bundle and note effective date