award/CLAUDE.md

Default to using Bun instead of Node.js.

• Use bun <file> instead of node <file> or ts-node <file>
• Use bun test instead of jest or vitest
• Use bun build <file.html|file.ts|file.css> instead of webpack or esbuild
• Use bun install instead of npm install or yarn install or pnpm install
• Use bun run <script> instead of npm run <script> or yarn run <script> or pnpm run <script>
• Use bunx <package> <command> instead of npx <package> <command>
• Bun automatically loads .env, so don't use dotenv.

APIs

• Bun.serve() supports WebSockets, HTTPS, and routes. Don't use express.
• bun:sqlite for SQLite. Don't use better-sqlite3.
• Bun.redis for Redis. Don't use ioredis.
• Bun.sql for Postgres. Don't use pg or postgres.js.
• WebSocket is built-in. Don't use ws.
• Prefer Bun.file over node:fs's readFile/writeFile
• Bun.$ls instead of execa.

Logging

The application uses a custom logger that outputs to both files and console.

Backend Logging

Backend logs are written to logs/backend.log:

• Log levels: debug (0), info (1), warn (2), error (3)
• Default: debug in development, info in production
• Override: Set LOG_LEVEL environment variable (e.g., LOG_LEVEL=debug)
• Output format: [timestamp] LEVEL: message with JSON data
• Console: Also outputs to console in development mode
• File: Always writes to logs/backend.log

Frontend Logging

Frontend logs are sent to the backend and written to logs/frontend.log:

• Logger: src/frontend/src/lib/logger.js
• Endpoint: POST /api/logs
• Batching: Batches logs (up to 10 entries or 5 seconds) for performance
• User context: Automatically includes userId and user-agent
• Levels: Same as backend (debug, info, warn, error)

Usage in frontend:

import { logger } from '$lib/logger';

logger.info('User action', { action: 'click', element: 'button' });
logger.error('API error', { error: err.message });
logger.warn('Deprecated feature used');
logger.debug('Component state', { state: componentState });

Important: The logger uses the nullish coalescing operator (??) to handle log levels. This ensures that debug (level 0) is not treated as falsy.

Example .env file:

NODE_ENV=development
LOG_LEVEL=debug

Log Files:

• logs/backend.log - Backend server logs
• logs/frontend.log - Frontend client logs
• Logs are excluded from git via .gitignore

Testing

Use bun test to run tests.

import { test, expect } from "bun:test";

test("hello world", () => {
  expect(1).toBe(1);
});

Docker Deployment

The application supports Docker deployment with single-port architecture and host-mounted database persistence.

Quick Start:

# Create environment file
cp .env.docker.example .env

# Generate JWT secret
openssl rand -base64 32  # Add to .env as JWT_SECRET

# Start application
docker-compose up -d --build

# Access at http://localhost:3001

Architecture:

• Single Port: Port 3001 serves both API (/api/*) and frontend (all other routes)
• Database Persistence: SQLite database stored at ./data/award.db on host
• Auto-initialization: Database created from template on first startup
• Health Checks: Built-in health monitoring at /api/health

Key Docker Files:

• Dockerfile: Multi-stage build using official Bun runtime
• docker-compose.yml: Stack orchestration with volume mounts
• docker-entrypoint.sh: Database initialization logic
• .env.docker.example: Environment variable template
• DOCKER.md: Complete deployment documentation

Environment Variables:

• NODE_ENV: Environment mode (default: production)
• PORT: Application port (default: 3001)
• LOG_LEVEL: Logging level (debug/info/warn/error)
• JWT_SECRET: JWT signing secret (required, change in production!)
• VITE_APP_URL: Your application's public URL
• ALLOWED_ORIGINS: CORS allowed origins (comma-separated)

Database Management:

• Database location: ./data/award.db (host-mounted volume)
• Backups: cp data/award.db data/award.db.backup.$(date +%Y%m%d)
• Reset: docker-compose down -v && docker-compose up -d

Important Notes:

• Database persists across container restarts/recreations
• Frontend dependencies are reinstalled in container to ensure correct platform binaries
• Uses custom init script (src/backend/scripts/init-db.js) with bun:sqlite
• Architecture-agnostic (works on x86, ARM64, etc.)

For detailed documentation, see DOCKER.md.

Frontend

Use HTML imports with Bun.serve(). Don't use vite. HTML imports fully support React, CSS, Tailwind.

Server:

import index from "./index.html"

Bun.serve({
  routes: {
    "/": index,
    "/api/users/:id": {
      GET: (req) => {
        return new Response(JSON.stringify({ id: req.params.id }));
      },
    },
  },
  // optional websocket support
  websocket: {
    open: (ws) => {
      ws.send("Hello, world!");
    },
    message: (ws, message) => {
      ws.send(message);
    },
    close: (ws) => {
      // handle close
    }
  },
  development: {
    hmr: true,
    console: true,
  }
})

HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. <link> tags can point to stylesheets and Bun's CSS bundler will bundle.

<html>
  <body>
    <h1>Hello, world!</h1>
    <script type="module" src="./frontend.tsx"></script>
  </body>
</html>

With the following frontend.tsx:

import React from "react";
import { createRoot } from "react-dom/client";

// import .css files directly and it works
import './index.css';

const root = createRoot(document.body);

export default function Frontend() {
  return <h1>Hello, world!</h1>;
}

root.render(<Frontend />);

Then, run index.ts

bun --hot ./index.ts

For more information, read the Bun API docs in node_modules/bun-types/docs/**.mdx.

Project: Quickawards by DJ7NT

Quickawards is a amateur radio award tracking application that calculates progress toward various awards based on QSO (contact) data.

Award System Architecture

The award system is JSON-driven and located in award-definitions/ directory. Each award has:

• id: Unique identifier (e.g., "dld", "dxcc")
• name: Display name
• description: Short description
• caption: Detailed explanation
• category: Award category ("dxcc", "darc", etc.)
• rules: Award calculation logic

Award Rule Types

1. entity: Count unique entities (DXCC countries, states, grid squares)

   • entityType: What to count ("dxcc", "state", "grid", "callsign")
   • target: Number required for award
   • filters: Optional filters (band, mode, etc.)
   • displayField: Optional field to display

2. dok: Count unique DOK (DARC Ortsverband Kennung) combinations

   • target: Number required
   • confirmationType: "dcl" (DARC Community Logbook)
   • filters: Optional filters (band, mode, etc.) for award variants
   • Counts unique (DOK, band, mode) combinations
   • Only DCL-confirmed QSOs count
   • Example variants: DLD 80m, DLD CW, DLD 80m CW

3. points: Point-based awards

   • stations: Array of {callsign, points}
   • target: Points required
   • countMode: "perStation", "perBandMode", or "perQso"

4. filtered: Filtered version of another award

   • baseRule: The base entity rule
   • filters: Additional filters to apply

5. counter: Count QSOs or callsigns

Key Files

Backend Award Service: src/backend/services/awards.service.js

• getAllAwards(): Returns all available award definitions
• calculateAwardProgress(userId, award, options): Main calculation function
• calculateDOKAwardProgress(userId, award, options): DOK-specific calculation
• calculatePointsAwardProgress(userId, award, options): Point-based calculation
• getAwardEntityBreakdown(userId, awardId): Detailed entity breakdown
• getAwardProgressDetails(userId, awardId): Progress with details

Database Schema: src/backend/db/schema/index.js

• QSO fields include: darcDok, dclQslRstatus, dclQslRdate
• DOK fields support DLD award tracking
• DCL confirmation fields separate from LoTW

Award Definitions: award-definitions/*.json

• Add new awards by creating JSON definition files
• Add filename to loadAwardDefinitions() file list in awards.service.js

ADIF Parser: src/backend/utils/adif-parser.js

• parseADIF(adifData): Parse ADIF format into QSO records
  • Handles case-insensitive <EOR> delimiters (supports <EOR>, <eor>, <Eor>)
  • Uses matchAll() for reliable field parsing
  • Skips header records automatically
• parseDCLResponse(response): Parse DCL's JSON response format { "adif": "..." }
• normalizeBand(band): Standardize band names (80m, 40m, etc.)
• normalizeMode(mode): Standardize mode names (CW, FT8, SSB, etc.)
• Used by both LoTW and DCL services for consistency

Job Queue Service: src/backend/services/job-queue.service.js

• Manages async background jobs for LoTW and DCL sync
• enqueueJob(userId, jobType): Queue a sync job ('lotw_sync' or 'dcl_sync')
• processJobAsync(jobId, userId, jobType): Process job asynchronously
• getUserActiveJob(userId, jobType): Get active job for user (optional type filter)
• getJobStatus(jobId): Get job status with parsed result
• updateJobProgress(jobId, progressData): Update job progress during processing
• Supports concurrent LoTW and DCL sync jobs
• Job types: 'lotw_sync', 'dcl_sync'
• Job status: 'pending', 'running', 'completed', 'failed'

Backend API Routes (src/backend/index.js):

• POST /api/lotw/sync: Queue LoTW sync job
• POST /api/dcl/sync: Queue DCL sync job
• GET /api/jobs/:jobId: Get job status
• GET /api/jobs/active: Get active job for current user
• GET /*: Serves static files from src/frontend/build/ with SPA fallback

SPA Routing: The backend serves the SvelteKit frontend build from src/frontend/build/.

• Paths with file extensions (.js, .css, etc.) are served as static files
• Paths without extensions (e.g., /qsos, /awards) are served index.html for client-side routing
• Common missing files like /favicon.ico return 404 immediately
• If frontend build is missing entirely, returns a user-friendly 503 HTML page
• Prevents ugly Bun error pages when accessing client-side routes via curl or non-JS clients

DCL Service: src/backend/services/dcl.service.js

• fetchQSOsFromDCL(dclApiKey, sinceDate): Fetch from DCL API
• API Endpoint: https://dings.dcl.darc.de/api/adiexport
• Request: POST with JSON body { key, limit: 50000, qsl_since, qso_since, cnf_only }
  • cnf_only: null - Fetch ALL QSOs (confirmed + unconfirmed)
  • cnf_only: true - Fetch only confirmed QSOs (dcl_qsl_rcvd='Y')
  • qso_since: DATE - QSOs since this date (YYYYMMDD format)
  • qsl_since: DATE - QSL confirmations since this date (YYYYMMDD format)
• parseDCLJSONResponse(jsonResponse): Parse example/test payloads
• syncQSOs(userId, dclApiKey, sinceDate, jobId): Sync QSOs to database
• getLastDCLQSLDate(userId): Get last QSL date for incremental sync
• getLastDCLQSODate(userId): Get last QSO date for incremental sync
• Debug logging (when LOG_LEVEL=debug) shows API params with redacted key (first/last 4 chars)
• Fully implemented and functional
• Note: DCL API is a custom prototype by DARC; contact DARC for API specification details

DLD Award Implementation (COMPLETED)

The DLD (Deutschland Diplom) award was recently implemented:

Definition: award-definitions/dld.json

{
  "id": "dld",
  "name": "DLD",
  "description": "Deutschland Diplom - Confirm 100 unique DOKs on different bands/modes",
  "caption": "Contact and confirm stations with 100 unique DOKs (DARC Ortsverband Kennung) on different band/mode combinations.",
  "category": "darc",
  "rules": {
    "type": "dok",
    "target": 100,
    "confirmationType": "dcl",
    "displayField": "darcDok"
  }
}

Implementation Details:

• Function: calculateDOKAwardProgress() in src/backend/services/awards.service.js (lines 173-268)
• Counts unique (DOK, band, mode) combinations
• Only DCL-confirmed QSOs count (dclQslRstatus === 'Y')
• Each unique DOK on each unique band/mode counts separately
• Returns worked, confirmed counts and entity breakdowns

Database Fields Used:

• darcDok: DOK identifier (e.g., "F03", "P30", "G20")
• band: Band (e.g., "80m", "40m", "20m")
• mode: Mode (e.g., "CW", "SSB", "FT8")
• dclQslRstatus: DCL confirmation status ('Y' = confirmed)
• dclQslRdate: DCL confirmation date

Documentation: See docs/DOCUMENTATION.md for complete documentation including DLD award example.

Frontend: src/frontend/src/routes/qsos/+page.svelte

• Separate sync buttons for LoTW (blue) and DCL (orange)
• Independent progress tracking for each sync type
• Both syncs can run simultaneously
• Job polling every 2 seconds for status updates
• Import log displays after sync completion
• Real-time QSO table refresh after sync

Frontend API (src/frontend/src/lib/api.js):

• qsosAPI.syncFromLoTW(): Trigger LoTW sync
• qsosAPI.syncFromDCL(): Trigger DCL sync
• jobsAPI.getStatus(jobId): Poll job status
• jobsAPI.getActive(): Get active job on page load

Adding New Awards

To add a new award:

1. Create JSON definition in award-definitions/
2. Add filename to loadAwardDefinitions() in src/backend/services/awards.service.js
3. If new rule type needed, add calculation function
4. Add type handling in calculateAwardProgress() switch statement
5. Add type handling in getAwardEntityBreakdown() if needed
6. Update documentation in docs/DOCUMENTATION.md
7. Test with sample QSO data

Creating DLD Award Variants

The DOK award type supports filters to create award variants. Examples:

DLD on 80m (dld-80m.json):

{
  "id": "dld-80m",
  "name": "DLD 80m",
  "description": "Confirm 100 unique DOKs on 80m",
  "caption": "Contact 100 different DOKs on the 80m band.",
  "category": "darc",
  "rules": {
    "type": "dok",
    "target": 100,
    "confirmationType": "dcl",
    "displayField": "darcDok",
    "filters": {
      "operator": "AND",
      "filters": [
        { "field": "band", "operator": "eq", "value": "80m" }
      ]
    }
  }
}

DLD in CW mode (dld-cw.json):

{
  "rules": {
    "type": "dok",
    "target": 100,
    "confirmationType": "dcl",
    "filters": {
      "operator": "AND",
      "filters": [
        { "field": "mode", "operator": "eq", "value": "CW" }
      ]
    }
  }
}

DLD on 80m using CW (combined filters, dld-80m-cw.json):

{
  "rules": {
    "type": "dok",
    "target": 100,
    "confirmationType": "dcl",
    "filters": {
      "operator": "AND",
      "filters": [
        { "field": "band", "operator": "eq", "value": "80m" },
        { "field": "mode", "operator": "eq", "value": "CW" }
      ]
    }
  }
}

Available filter operators:

• eq: equals
• ne: not equals
• in: in array
• nin: not in array
• contains: contains substring

Available filter fields: Any QSO field (band, mode, callsign, grid, state, satName, etc.)

Confirmation Systems

• LoTW (Logbook of The World): ARRL's confirmation system

  • Service: src/backend/services/lotw.service.js
  • API: https://lotw.arrl.org/lotwuser/lotwreport.adi
  • Fields: lotwQslRstatus, lotwQslRdate
  • Used for DXCC, WAS, VUCC, most awards
  • ADIF format with <EOR> delimiters
  • Supports incremental sync by qso_qslsince parameter (format: YYYY-MM-DD)

• DCL (DARC Community Logbook): DARC's confirmation system

  • Service: src/backend/services/dcl.service.js
  • API: https://dings.dcl.darc.de/api/adiexport
  • Fields: dclQslRstatus, dclQslRdate
  • DOK fields: darcDok (partner's DOK), myDarcDok (user's DOK)
  • Required for DLD award
  • German amateur radio specific
  • Request format: POST JSON { key, limit, qsl_since, qso_since, cnf_only }
    • cnf_only: null - Fetch all QSOs (confirmed + unconfirmed)
    • cnf_only: true - Fetch only confirmed QSOs
    • qso_since - QSOs since this date (YYYYMMDD)
    • qsl_since - QSL confirmations since this date (YYYYMMDD)
  • Response format: JSON with ADIF string in adif field
  • Syncs ALL QSOs (both confirmed and unconfirmed)
  • Unconfirmed QSOs stored but don't count toward awards
  • Updates QSOs only if confirmation data has changed

ADIF Format

Both LoTW and DCL return data in ADIF (Amateur Data Interchange Format):

• Field format: <FIELD_NAME:length>value
• Record delimiter: <EOR> (end of record, case-insensitive)
• Header ends with: <EOH> (end of header)
• Example: <CALL:5>DK0MU<BAND:3>80m<QSO_DATE:8>20250621<EOR>
• Important: Parser handles case-insensitive <EOR>, <eor>, <Eor> tags

DCL-specific fields:

• DCL_QSL_RCVD: DCL confirmation status (Y/N/?)
• DCL_QSLRDATE: DCL confirmation date (YYYYMMDD)
• DARC_DOK: QSO partner's DOK
• MY_DARC_DOK: User's own DOK
• STATION_CALLSIGN: User's callsign

Recent Commits

• aeeb75c: feat: add QSO count display to filter section
  • Shows count of QSOs matching current filters next to "Filters" heading
  • Displays "Showing X filtered QSOs" when filters are active
  • Displays "Showing X total QSOs" when no filters applied
  • Dynamically updates when filters change
• bee02d1: fix: count QSOs confirmed by either LoTW or DCL in stats
  • QSO stats were only counting LoTW-confirmed QSOs (lotwQslRstatus === 'Y')
  • QSOs confirmed only by DCL were excluded from "confirmed" count
  • Fixed by changing filter to: q.lotwQslRstatus === 'Y' || q.dclQslRstatus === 'Y'
  • Now correctly shows all QSOs confirmed by at least one system
• 233888c: fix: make ADIF parser case-insensitive for EOR delimiter
  • Critical bug: LoTW uses lowercase <eor> tags, parser was splitting on uppercase <EOR>
  • Caused 242K+ QSOs to be parsed as 1 giant record with fields overwriting each other
  • Changed to case-insensitive regex: new RegExp('<eor>', 'gi')
  • Replaced regex.exec() while loop with matchAll() for-of iteration
  • Now correctly imports all QSOs from large LoTW reports
• 645f786: fix: add missing timeOn field to LoTW duplicate detection
  • LoTW sync was missing timeOn in duplicate detection query
  • Multiple QSOs with same callsign/date/band/mode but different times were treated as duplicates
  • Now matches DCL sync logic: userId, callsign, qsoDate, timeOn, band, mode
• 7f77c3a: feat: add filter support for DOK awards
  • DOK award type now supports filtering by band, mode, and other QSO fields
  • Allows creating award variants like DLD 80m, DLD CW, DLD 80m CW
  • Uses existing filter system with eq, ne, in, nin, contains operators
  • Example awards created: dld-80m, dld-40m, dld-cw, dld-80m-cw
• 9e73704: docs: update CLAUDE.md with DLD award variants documentation
• 7201446: fix: return proper HTML for SPA routes instead of Bun error page
  • When accessing client-side routes (like /qsos) via curl or non-JS clients, the server attempted to open them as static files, causing Bun to throw an unhandled ENOENT error that showed an ugly error page
  • Now checks if a path has a file extension before attempting to serve it
  • Paths without extensions are immediately served index.html for SPA routing
  • Also improves the 503 error page with user-friendly HTML when frontend build is missing
• 223461f: fix: enable debug logging and improve DCL sync observability
• 27d2ef1: fix: preserve DOK data when DCL doesn't send values
  • DCL sync only updates DOK/grid fields when DCL provides non-empty values
  • Prevents accidentally clearing DOK data from manual entry or other sources
  • Preserves existing DOK when DCL syncs QSO without DOK information
• e09ab94: feat: skip QSOs with unchanged confirmation data
  • LoTW/DCL sync only updates QSOs if confirmation data has changed
  • Tracks added, updated, and skipped QSO counts
  • LoTW: Checks if lotwQslRstatus or lotwQslRdate changed
  • DCL: Checks if dclQslRstatus, dclQslRdate, darcDok, myDarcDok, or grid changed
• 3592dbb: feat: add import log showing synced QSOs
  • Backend returns addedQSOs and updatedQSOs arrays in sync result
  • Frontend displays import log with callsign, date, band, mode for each QSO
  • Separate sections for "New QSOs" and "Updated QSOs"
  • Sync summary shows total, added, updated, skipped counts
• 8a1a580: feat: implement DCL ADIF parser and service integration
  • Add shared ADIF parser utility (src/backend/utils/adif-parser.js)
  • Implement DCL service with API integration
  • Refactor LoTW service to use shared parser
  • Tested with example DCL payload (6 QSOs parsed successfully)
• c982dcd: feat: implement DLD (Deutschland Diplom) award
• 322ccaf: docs: add DLD (Deutschland Diplom) award documentation

Sync Behavior

Import Log: After each sync, displays a table showing:

• New QSOs: Callsign, Date, Band, Mode
• Updated QSOs: Callsign, Date, Band, Mode (only if data changed)
• Skipped QSOs: Counted but not shown (data unchanged)

Duplicate Handling:

• QSOs matched by: userId, callsign, qsoDate, timeOn, band, mode
• If confirmation data unchanged: Skipped (not updated)
• If confirmation data changed: Updated with new values
• Prevents unnecessary database writes and shows accurate import counts

DOK Update Behavior:

• If QSO imported via LoTW (no DOK) and later DCL confirms with DOK: DOK is added ✓
• If QSO already has DOK and DCL sends different DOK: DOK is updated ✓
• If QSO has DOK and DCL syncs without DOK (empty): Existing DOK is preserved ✓
• LoTW never sends DOK data; only DCL provides DOK fields

Important: DCL sync only updates DOK/grid fields when DCL provides non-empty values. This prevents accidentally clearing DOK data that was manually entered or imported from other sources.

DCL Sync Strategy

Current Behavior: DCL syncs ALL QSOs (confirmed + unconfirmed)

The application syncs both confirmed and unconfirmed QSOs from DCL:

• Confirmed QSOs: dclQslRstatus = 'Y' - Count toward awards
• Unconfirmed QSOs: dclQslRstatus = 'N' - Stored but don't count toward awards

Purpose of syncing unconfirmed QSOs:

• Users can see who they've worked (via "Not Confirmed" filter)
• Track QSOs awaiting confirmation
• QSOs can get confirmed later and will be updated on next sync

Award Calculation: Always uses confirmed QSOs only (e.g., dclQslRstatus === 'Y' for DLD award)

DCL Incremental Sync Strategy

Challenge: Need to fetch both new QSOs AND confirmation updates to old QSOs

Example Scenario:

1. Full sync on 2026-01-20 → Last QSO date: 2026-01-20
2. User works 3 new QSOs on 2026-01-25 (unconfirmed)
3. Old QSO from 2026-01-10 gets confirmed on 2026-01-26
4. Next sync needs both: new QSOs (2026-01-25) AND confirmation update (2026-01-10)

Solution: Use both qso_since and qsl_since parameters with OR logic

// Proposed sync logic (requires OR logic from DCL API)
const lastQSODate = await getLastDCLQSODate(userId);  // Track QSO dates
const lastQSLDate = await getLastDCLQSLDate(userId);  // Track QSL dates

const requestBody = {
  key: dclApiKey,
  limit: 50000,
  qso_since: lastQSODate,  // Get new QSOs since last contact
  qsl_since: lastQSLDate,  // Get QSL confirmations since last sync
  cnf_only: null,          // Fetch all QSOs
};

Required API Behavior (OR Logic):

• Return QSOs where (qso_date >= qso_since) OR (qsl_date >= qsl_since)
• This ensures we get both new QSOs and confirmation updates

Current DCL API Status:

• Unknown if current API uses AND or OR logic for combined filters
• Action Needed: Request OR logic implementation from DARC
• Test current behavior to confirm API response pattern

Why OR Logic is Needed:

• With AND logic: Old QSOs getting confirmed are missed (qso_date too old)
• With OR logic: All updates captured efficiently in one API call

QSO Page Filters

The QSO page (src/frontend/src/routes/qsos/+page.svelte) includes advanced filtering capabilities:

Available Filters:

• Search Box: Full-text search across callsign, entity (DXCC country), and grid square fields
  • Press Enter to apply search
  • Case-insensitive partial matching
• Band Filter: Dropdown to filter by amateur band (160m, 80m, 60m, 40m, 30m, 20m, 17m, 15m, 12m, 10m, 6m, 2m, 70cm)
• Mode Filter: Dropdown to filter by mode (CW, SSB, AM, FM, RTTY, PSK31, FT8, FT4, JT65, JT9)
• Confirmation Type Filter: Filter by confirmation status
  • "All QSOs": Shows all QSOs (no filter)
  • "LoTW Only": Shows QSOs confirmed by LoTW but NOT DCL
  • "DCL Only": Shows QSOs confirmed by DCL but NOT LoTW
  • "Both Confirmed": Shows QSOs confirmed by BOTH LoTW AND DCL
  • "Not Confirmed": Shows QSOs confirmed by NEITHER LoTW nor DCL
• Clear Button: Resets all filters and reloads all QSOs

Backend Implementation (src/backend/services/lotw.service.js):

• getUserQSOs(userId, filters, options): Main filtering function
• Supports pagination with page and limit options
• Filter logic uses Drizzle ORM query builders for safe SQL generation
• Debug logging when LOG_LEVEL=debug shows applied filters

Frontend API (src/frontend/src/lib/api.js):

• qsosAPI.getAll(filters): Fetch QSOs with optional filters
• Filters passed as query parameters: ?band=20m&mode=CW&confirmationType=lotw&search=DL

QSO Count Display:

• Shows count of QSOs matching current filters next to "Filters" heading
• With filters active: "Showing X filtered QSOs"
• No filters: "Showing X total QSOs"
• Dynamically updates when filters are applied or cleared
• Uses pagination.totalCount from backend API response

DXCC Entity Priority Logic

When syncing QSOs from multiple confirmation sources, the system follows a priority order for DXCC entity data:

Priority Order: LoTW > DCL

Implementation (src/backend/services/dcl.service.js):

// DXCC priority: LoTW > DCL
// Only update entity fields from DCL if:
// 1. QSO is NOT LoTW confirmed, AND
// 2. DCL actually sent entity data, AND
// 3. Current entity is missing
const hasLoTWConfirmation = existingQSO.lotwQslRstatus === 'Y';
const hasDCLData = dbQSO.entity || dbQSO.entityId;
const missingEntity = !existingQSO.entity || existingQSO.entity === '';

if (!hasLoTWConfirmation && hasDCLData && missingEntity) {
  // Fill in entity data from DCL (only if DCL provides it)
  updateData.entity = dbQSO.entity;
  updateData.entityId = dbQSO.entityId;
  // ... other entity fields
}

Rules:

1. LoTW-confirmed QSOs: Always use LoTW's DXCC data (most reliable)
2. DCL-only QSOs: Use DCL's DXCC data IF available in ADIF payload
3. Empty entity fields: If DCL doesn't send DXCC data, entity remains empty
4. Never overwrite: Once LoTW confirms with entity data, DCL sync won't change it

Important Note: DCL API currently doesn't send DXCC/entity fields in their ADIF export. This is a limitation of the DCL API, not the application. If DCL adds these fields in the future, the system will automatically use them for DCL-only QSOs.

Recent Development Work (January 2025)

QSO Page Enhancements:

• Added confirmation type filter with exclusive logic (LoTW Only, DCL Only, Both Confirmed, Not Confirmed)
• Added search box for filtering by callsign, entity, or grid square
• Renamed "All Confirmation" to "All QSOs" for clarity
• Fixed filter logic to properly handle exclusive confirmation types

Bug Fixes:

• Fixed confirmation filter showing wrong QSOs (e.g., "LoTW Only" was also showing DCL QSOs)
• Implemented proper SQL conditions for exclusive filters using separate condition pushes
• Added debug logging to track filter application

DXCC Entity Handling:

• Clarified that DCL API doesn't send DXCC fields (current limitation)
• Implemented priority logic: LoTW entity data takes precedence over DCL
• System ready to auto-use DCL DXCC data if they add it in future API updates