Ham Radio Award Portal

A web application for amateur radio operators to track QSOs (contacts) and award progress using Logbook of the World (LoTW) data.

Features

• User Authentication: Register and login with callsign, email, and password
• LoTW Integration: Sync QSOs from ARRL's Logbook of the World
  • Background job queue for non-blocking sync operations
  • Incremental sync using last confirmation date
  • Wavelog-compatible download logic with proper validation
  • One sync job per user enforcement
• QSO Log: View and manage confirmed QSOs
  • Pagination support for large QSO collections
  • Filter by band, mode, and confirmation status
  • Statistics dashboard (total QSOs, confirmed, DXCC entities, bands)
  • Delete all QSOs with confirmation
• Settings: Configure LoTW credentials securely

Tech Stack

Backend

• Runtime: Bun
• Framework: Elysia.js
• Database: SQLite with Drizzle ORM
• Authentication: JWT tokens
• Logging: Pino with structured logging and timestamps

Frontend

• Framework: SvelteKit
• Language: JavaScript
• Styling: Custom CSS

Project Structure

award/
├── src/
│   ├── backend/
│   │   ├── config/
│   │   │   ├── database.js     # Database connection
│   │   │   ├── jwt.js          # JWT configuration
│   │   │   └── logger.js       # Pino logging configuration
│   │   ├── db/
│   │   │   └── schema/
│   │   │       └── index.js    # Database schema (users, qsos, sync_jobs)
│   │   ├── services/
│   │   │   ├── auth.service.js        # User authentication
│   │   │   ├── lotw.service.js        # LoTW sync & QSO management
│   │   │   └── job-queue.service.js   # Background job queue
│   │   └── index.js            # API routes and server
│   └── frontend/
│       ├── src/
│       │   ├── lib/
│       │   │   ├── api.js      # API client
│       │   │   └── stores.js   # Svelte stores (auth)
│       │   └── routes/
│       │       ├── +layout.svelte       # Navigation bar & layout
│       │       ├── +page.svelte         # Dashboard
│       │       ├── auth/
│       │       │   ├── login/+page.svelte   # Login page
│       │       │   └── register/+page.svelte # Registration page
│       │       ├── qsos/+page.svelte    # QSO log with pagination
│       │       └── settings/+page.svelte # Settings & LoTW credentials
│       └── package.json
├── award.db                   # SQLite database (auto-created)
├── drizzle.config.js          # Drizzle ORM configuration
├── package.json
└── README.md

Setup

Prerequisites

• Bun v1.3.6 or later

Installation

1. Clone the repository:

git clone <repository-url>
cd award

2. Install dependencies:

bun install

3. Set up environment variables (optional): Create a .env file in the project root:

JWT_SECRET=your-secret-key-here

If not provided, a default secret will be used.

4. Initialize the database:

bun run db:push

This creates the SQLite database with required tables (users, qsos, sync_jobs).

Running the Application

Start both backend and frontend with a single command:

bun run dev

Or start them individually:

# Backend only (port 3001, proxied)
bun run dev:backend

# Frontend only (port 5173)
bun run dev:frontend

The application will be available at:

• Frontend & API: http://localhost:5173

Note: During development, both servers run (frontend on 5173, backend on 3001), but API requests are automatically proxied through the frontend. You only need to access port 5173.

API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login user
• GET /api/auth/me - Get current user profile
• PUT /api/auth/lotw-credentials - Update LoTW credentials

LoTW Sync

• POST /api/lotw/sync - Queue a LoTW sync job (returns job ID)

Jobs

• GET /api/jobs/:jobId - Get job status
• GET /api/jobs/active - Get user's active job
• GET /api/jobs - Get recent jobs (query: ?limit=10)

QSOs

• GET /api/qsos - Get user's QSOs with pagination
  • Query parameters: ?page=1&limit=100&band=20m&mode=CW&confirmed=true
• GET /api/qsos/stats - Get QSO statistics
• DELETE /api/qsos/all - Delete all QSOs (requires confirmation)

Health

• GET /api/health - Health check endpoint

Database Schema

Users Table

CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  email TEXT UNIQUE NOT NULL,
  password TEXT NOT NULL,
  callsign TEXT NOT NULL,
  lotwUsername TEXT,
  lotwPassword TEXT,
  createdAt TEXT NOT NULL
);

QSOs Table

CREATE TABLE qsos (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  userId INTEGER NOT NULL,
  callsign TEXT NOT NULL,
  qsoDate TEXT NOT NULL,
  timeOn TEXT NOT NULL,
  band TEXT,
  mode TEXT,
  entity TEXT,
  grid TEXT,
  lotwQslRstatus TEXT,
  lotwQslRdate TEXT,
  FOREIGN KEY (userId) REFERENCES users(id)
);

Sync Jobs Table

CREATE TABLE sync_jobs (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  userId INTEGER NOT NULL,
  status TEXT NOT NULL, -- pending, running, completed, failed
  type TEXT NOT NULL,   -- lotw_sync
  startedAt INTEGER,
  completedAt INTEGER,
  result TEXT,          -- JSON
  error TEXT,
  createdAt INTEGER NOT NULL,
  FOREIGN KEY (userId) REFERENCES users(id)
);

Architecture

Development Mode

• SvelteKit Dev Server (port 5173): Serves frontend and proxies API requests
• Elysia Backend (port 3001): Handles API requests (hidden from user)
• Proxy Configuration: All /api/* requests are forwarded from SvelteKit to Elysia

This gives you:

• ✅ Single port to access (5173)
• ✅ Hot Module Replacement (HMR) for frontend
• ✅ No CORS issues
• ✅ Simple production deployment

Production Mode

In production, you can either:

1. Build static files and serve from Elysia
2. Keep the proxy setup with a proper reverse proxy (nginx, caddy)
3. Use SvelteKit adapter for Node/Bun to serve everything from one process

Features in Detail

Background Job Queue

The application uses an in-memory job queue system for async operations:

• Jobs are persisted to database for recovery
• Only one active job per user (enforced at queue level)
• Status tracking: pending → running → completed/failed
• Real-time progress updates via job result field
• Client polls job status every 2 seconds

LoTW Sync Logic

Following Wavelog's proven approach:

1. First sync: Uses date 2000-01-01 to retrieve all QSOs
2. Subsequent syncs: Uses MAX(lotwQslRdate) from database
3. Validation:
   • Checks for "Username/password incorrect" in response
   • Validates file starts with "ARRL Logbook of the World Status Report"
4. Timeout handling: 30-second connection timeout
5. Query parameters: Matches Wavelog's LoTW download

Pagination

• Default page size: 100 QSOs per page
• Supports custom page size via limit parameter
• Shows page numbers with ellipsis for large page counts
• Displays "Showing X-Y of Z" info
• Previous/Next navigation buttons

Development

Database Migrations

# Push schema changes to database
bun run db:push

# Open Drizzle Studio (database GUI)
bun run db:studio

Linting

bun run lint

License

MIT

Credits

• LoTW integration inspired by Wavelog
• Built with Bun, Elysia, and SvelteKit