openhamclock/README.md

OpenHamClock - Modular React Architecture

A modern, modular amateur radio dashboard built with React and Vite. This is the fully extracted modular version - all components, hooks, and utilities are already separated into individual files.

🚀 Quick Start

# Install dependencies
npm install

# Start development servers (need two terminals)
# Terminal 1: Backend API server
node server.js

# Terminal 2: Frontend dev server with hot reload
npm run dev

# Open http://localhost:3000

For production:

npm run build
npm start  # Serves from dist/ on port 3001

📁 Project Structure

openhamclock-modular/
├── src/
│   ├── main.jsx              # React entry point
│   ├── App.jsx               # Main application component
│   ├── components/           # All UI components (fully extracted)
│   │   ├── index.js          # Component exports
│   │   ├── Header.jsx        # Top bar with clocks/controls
│   │   ├── WorldMap.jsx      # Leaflet map with DX paths
│   │   ├── SpaceWeatherPanel.jsx
│   │   ├── BandConditionsPanel.jsx
│   │   ├── DXClusterPanel.jsx
│   │   ├── POTAPanel.jsx
│   │   ├── ContestPanel.jsx
│   │   ├── LocationPanel.jsx
│   │   ├── SettingsPanel.jsx
│   │   └── DXFilterManager.jsx
│   ├── hooks/                # All data fetching hooks (fully extracted)
│   │   ├── index.js          # Hook exports
│   │   ├── useSpaceWeather.js
│   │   ├── useBandConditions.js
│   │   ├── useDXCluster.js
│   │   ├── useDXPaths.js
│   │   ├── usePOTASpots.js
│   │   ├── useContests.js
│   │   ├── useLocalWeather.js
│   │   ├── usePropagation.js
│   │   ├── useMySpots.js
│   │   ├── useDXpeditions.js
│   │   ├── useSatellites.js
│   │   └── useSolarIndices.js
│   ├── utils/                # Utility functions (fully extracted)
│   │   ├── index.js          # Utility exports
│   │   ├── config.js         # App config & localStorage
│   │   ├── geo.js            # Grid squares, bearings, distances
│   │   └── callsign.js       # Band detection, filtering
│   └── styles/
│       └── main.css          # All CSS with theme variables
├── public/
│   └── index-monolithic.html # Original 5714-line reference
├── server.js                 # Backend API server
├── config.js                 # Server configuration
├── package.json
├── vite.config.js
└── index.html                # Vite entry HTML

🎨 Themes

Three themes available via Settings:

• Dark (default) - Modern dark theme with amber accents
• Light - Light theme for daytime use
• Legacy - Classic HamClock green-on-black terminal style

Themes use CSS custom properties defined in src/styles/main.css.

🔌 Components

All components are fully extracted and ready to modify:

Component	Description	File
Header	Top bar with clocks, weather, controls	Header.jsx
WorldMap	Leaflet map with markers & paths	WorldMap.jsx
SpaceWeatherPanel	SFI, K-index, SSN display	SpaceWeatherPanel.jsx
BandConditionsPanel	HF band condition indicators	BandConditionsPanel.jsx
DXClusterPanel	Live DX spots list	DXClusterPanel.jsx
POTAPanel	Parks on the Air activations	POTAPanel.jsx
ContestPanel	Upcoming contests	ContestPanel.jsx
LocationPanel	DE/DX info with grid squares	LocationPanel.jsx
SettingsPanel	Configuration modal	SettingsPanel.jsx
DXFilterManager	DX cluster filtering modal	DXFilterManager.jsx

🪝 Hooks

All data fetching is handled by custom hooks:

Hook	Purpose	Interval
useSpaceWeather	SFI, K-index, SSN from NOAA	5 min
useBandConditions	Calculate band conditions	On SFI change
useDXCluster	DX spots with filtering	5 sec
useDXPaths	DX paths for map	10 sec
usePOTASpots	POTA activations	1 min
useContests	Contest calendar	30 min
useLocalWeather	Weather from Open-Meteo	15 min
usePropagation	ITURHFProp predictions	10 min
useMySpots	Your callsign spots	30 sec
useSatellites	Satellite tracking	5 sec
useSolarIndices	Extended solar data	15 min

🛠️ Utilities

Module	Functions
config.js	loadConfig, saveConfig, applyTheme, MAP_STYLES
geo.js	calculateGridSquare, calculateBearing, calculateDistance, getSunPosition, getMoonPosition, getGreatCirclePoints
callsign.js	getBandFromFreq, getBandColor, detectMode, getCallsignInfo, filterDXPaths

🌐 API Endpoints

The backend server provides:

Endpoint	Description
/api/dxcluster/spots	DX cluster spots
/api/dxcluster/paths	DX paths with coordinates
/api/solar-indices	Extended solar data
/api/propagation	HF propagation predictions
/api/contests	Contest calendar
/api/myspots/:callsign	Spots for your callsign
/api/satellites/tle	Satellite TLE data
/api/dxpeditions	Active DXpeditions

🚀 Deployment

Railway

# railway.toml and railway.json are included
railway up

Docker

docker-compose up -d

Manual

npm run build
NODE_ENV=production node server.js

🤝 Contributing

1. Fork the repository
2. Pick a component/hook to improve
3. Make changes in the appropriate file
4. Test with all three themes
5. Submit a PR

Code Style

• Functional components with hooks
• CSS-in-JS for component-specific styles
• CSS variables for theme colors
• JSDoc comments for functions
• Descriptive variable names

Testing Changes

# Run dev server
npm run dev

# Check all themes work
# Test on different screen sizes
# Verify data fetching works

📄 License

MIT License - See LICENSE file

🙏 Credits

• K0CJH - Original OpenHamClock
• NOAA SWPC - Space weather data
• POTA - Parks on the Air API
• Open-Meteo - Weather data
• Leaflet - Mapping library