Radio Propagation Service 📡

An intelligent amateur radio propagation reporting service that generates comprehensive daily reports by analyzing real-time solar and geomagnetic data using AI. The service provides detailed band-by-band propagation forecasts with interactive visualizations to help amateur radio operators optimize their communications.

🌟 Live Example

Visit the production service at radio-propagation.net to see live reports with:

Real-time solar activity analysis
Interactive propagation charts
Band-by-band recommendations
3-day forecasts
DX opportunity predictions

🎯 Purpose

This service addresses the amateur radio community's need for:

Intelligent Analysis: AI-powered interpretation of complex space weather data
Actionable Insights: Clear recommendations for each amateur radio band (10m-80m)
Visual Data: Interactive charts showing trends and forecasts
Accessibility: Easy-to-understand reports for operators of all experience levels
Automation: Daily reports generated without manual intervention

🏗️ Architecture

graph LR
    A[NOAA SWPC] --> D[Data Fetcher]
    B[N0NBH API] --> D
    C[SIDC RSS] --> D
    E[Helioviewer] --> D
    D --> F[OpenAI GPT-4]
    F --> G[Report Generator]
    G --> H[Interactive Charts]
    G --> I[HTML Reports]
    H --> J[Cloud Storage]
    I --> J
    J --> K[Daily Reports]

Data Flow:

Collection: Fetch solar/geomagnetic data from multiple authoritative sources
Analysis: OpenAI GPT-4 analyzes conditions and generates insights
Visualization: Create interactive charts using go-echarts
Generation: Combine analysis and charts into comprehensive HTML reports
Storage: Deploy reports to cloud storage with automated scheduling

🚀 Quick Start

Prerequisites

Go 1.21+ - Programming language runtime
OpenAI API Key - For AI-powered analysis (get one here)
Google Cloud Project - For production deployment (optional for local testing)

Local Development

Clone and setup:

git clone https://github.com/vpoluyaktov/radiocast.git
cd radiocast/service
go mod download

Set your OpenAI API key:

export OPENAI_API_KEY='sk-your-openai-key-here'

Run the local server (from the service/ directory):

./run_local.sh server

This will:

✅ Kill any existing process on port 8981
📡 Fetch real data from NOAA, N0NBH, and SIDC
🤖 Generate a report using OpenAI GPT-4
🌞 Download Sun images from Helioviewer
📊 Create HTML with interactive charts
🌐 Start server on http://localhost:8981

Test the service:

# Health check
curl http://localhost:8981/health

# Generate a new report (no API key required by default)
curl -X POST http://localhost:8981/generate

# View reports in browser
open http://localhost:8981

Fast Testing with Mock Data

For rapid development without API calls:

./run_local.sh server --mockup

📊 Report Features

Generated reports include comprehensive analysis with:

📈 Interactive Charts

Solar Activity: Real-time solar flux, sunspot numbers, and K-index
K-index Trend: 72-hour history with exponential moving average
Band Conditions: Heatmap showing day/night conditions for all amateur bands
3-Day Forecast: Predicted K-index and propagation quality
Propagation Timeline: Dual-axis charts showing solar flux and geomagnetic activity

📋 Analysis Sections

Executive Summary - Current conditions overview
Solar Activity Analysis - SFI, sunspot numbers, flare activity
Geomagnetic Conditions - K-index, A-index, storm levels
Band-by-Band Analysis - Specific recommendations for each amateur band (10m-80m)
3-Day Forecast - Predicted conditions and operating recommendations
DX Opportunities - Enhanced propagation paths and timing
Technical Explanation - Educational content for new operators

🛠️ Development Tools

Available Commands

Note: All ./run_local.sh commands must be run from the service/ directory.

# Run complete local test with real data
./run_local.sh server

# Fast testing with mock data (no API calls)
./run_local.sh server --mockup

# Test all external API endpoints
./run_local.sh debug-apis

# Run unit tests
./run_local.sh unit-tests

# Show help
./run_local.sh help

Testing & Quality

The project includes comprehensive unit tests with high coverage:

Config Package: ~85% coverage
Models Package: ~90% coverage
Storage Package: 55.6% coverage
Charts Package: 92.2% coverage

# Run all tests
go test -v ./...

# Run tests with coverage
go test -v -cover ./...

🌐 API Endpoints

`GET /` - Main Page

Displays the latest report or auto-generates one if none exist
Shows loading page with spinner during generation
Auto-refreshes every 10 seconds until report is ready

`GET /health` - Health Check

Health check endpoint for monitoring and load balancers.

`POST /generate` - Generate Report

Generates a new propagation report with concurrency protection.

API Key Protection: If the API_KEY environment variable is set, this endpoint requires authentication via the Authorization header.

Authentication (when API_KEY is configured):

# With API key
curl -X POST http://localhost:8981/generate \
  -H "Authorization: Bearer your-api-key-here"

Response (Success):

{
  "status": "success", 
  "report_url": "https://radio-propagation.net/2024/01/15/index.html",
  "timestamp": "2024-01-15T12:00:00Z",
  "duration_ms": 45000,
  "data_summary": {
    "solar_flux": 150.2,
    "k_index": 2.3,
    "sunspot_number": 45,
    "activity_level": "Moderate"
  }
}

Response (Concurrent Request):

{
  "error": "Report generation already in progress",
  "status": "conflict"
}

HTTP 409 Conflict - Only one report can be generated at a time

Response (Unauthorized - when API_KEY is configured):

{
  "error": "Missing Authorization header",
  "message": "This endpoint requires an API key. Please provide it in the Authorization header as 'Bearer <your-api-key>'",
  "status": "unauthorized"
}

HTTP 401 Unauthorized - API key required but not provided or invalid

`GET /reports?limit=10` - List Reports

Lists recent reports with metadata and direct links.

⚙️ Configuration

Variable	Description	Default	Required
`OPENAI_API_KEY`	OpenAI API key for GPT-4	-	✅
`OPENAI_MODEL`	OpenAI model to use	`gpt-4.1`	❌
`PORT`	HTTP server port	`8981`	❌
`ENVIRONMENT`	Deployment environment	`local`	❌
`GCP_PROJECT_ID`	GCP project (production only)	-	❌
`GCS_BUCKET`	GCS bucket (production only)	-	❌
`RADIOCAST_API_KEY`	API key for `/generate` endpoint protection	-	❌

🔐 API Security

The /generate endpoint can be protected with an API key to prevent unauthorized report generation.

Enabling API Key Protection

Set the RADIOCAST_API_KEY environment variable to enable protection:

export RADIOCAST_API_KEY="your-secret-api-key-here"
./run_local.sh server

Using the Protected Endpoint

When API key protection is enabled, include the key in the Authorization header:

# Correct usage with API key
curl -X POST http://localhost:8981/generate \
  -H "Authorization: Bearer your-secret-api-key-here"

# This will be rejected with HTTP 401
curl -X POST http://localhost:8981/generate

Backward Compatibility

No RADIOCAST_API_KEY configured: The /generate endpoint works without authentication (default behavior)
RADIOCAST_API_KEY configured: The /generate endpoint requires the Authorization: Bearer <key> header
Other endpoints: All other endpoints (/health, /reports, /, etc.) remain unprotected

Security Best Practices

Use a strong, randomly generated API key (minimum 32 characters)
Store the API key securely (environment variables, secret managers)
Rotate API keys regularly in production environments
Monitor logs for unauthorized access attempts

📡 Data Sources

The service integrates with multiple authoritative space weather data sources:

🌞 NOAA Space Weather Prediction Center

Website: swpc.noaa.gov
K-index Data: Real-time planetary geomagnetic activity
Solar Cycle Data: Solar flux index and sunspot numbers
Reliability: Primary government source for space weather

📊 N0NBH Solar Data API

Website: hamqsl.com
Band Conditions: Real-time HF propagation conditions for all amateur bands
Formatted Data: Pre-processed amateur radio specific metrics
Update Frequency: Multiple times per day

🌍 SIDC (Solar Influences Data Analysis Center)

Website: sidc.be
Solar Events: Flare reports and space weather events
International Data: European Space Agency collaboration
RSS Feed: Real-time event notifications

🌞 Helioviewer Project

Website: helioviewer.org
Solar Images: Real-time Sun imagery from SDO/AIA instruments
Visual Context: Provides visual representation of solar activity
NASA Data: Direct integration with space-based solar observatories

🏗️ Project Structure

radiocast/
├── service/                    # Go application
│   ├── main.go                # HTTP server entry point
│   ├── internal/
│   │   ├── config/            # Configuration management
│   │   ├── fetchers/          # Data source integrations  
│   │   ├── llm/               # OpenAI GPT-4 integration
│   │   ├── models/            # Data structures & types
│   │   ├── reports/           # HTML generation & templates
│   │   ├── charts/            # Interactive chart generation
│   │   ├── storage/           # Local & cloud storage
│   │   ├── server/            # HTTP handlers & middleware
│   │   └── imagery/           # Solar image processing
│   ├── templates/             # HTML & CSS templates
│   ├── run_local.sh          # Development runner script
│   └── Dockerfile            # Container build
├── terraform/                 # Infrastructure as Code
│   ├── stage/                # Staging environment
│   └── prod/                 # Production environment
└── .github/workflows/        # CI/CD automation

🚀 Production Deployment

The service runs on Google Cloud Platform with automated CI/CD:

Production URL: radio-propagation.net
Staging Environment: Automatic deployment from stage branch
Production Environment: Automatic deployment from main branch
Infrastructure: Managed via Terraform
Scheduling: Daily report generation via Cloud Scheduler
Storage: Reports stored in Google Cloud Storage
Monitoring: Cloud Run metrics and custom alerts

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Add tests for new functionality
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Maintain high test coverage (aim for >80%)
Follow Go best practices and conventions
Add unit tests for new packages/functions
Update documentation for API changes

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Live Example: radio-propagation.net

73! Happy DXing! 📡🌍

Name		Name	Last commit message	Last commit date
Latest commit History 270 Commits
.github/workflows		.github/workflows
service		service
terraform		terraform
.eslintignore		.eslintignore
.gitignore		.gitignore
README.md		README.md
VERSION		VERSION

Folders and files

Latest commit

History

Repository files navigation

Radio Propagation Service 📡

🌟 Live Example

🎯 Purpose

🏗️ Architecture

🚀 Quick Start

Prerequisites

Local Development

Fast Testing with Mock Data

📊 Report Features

📈 Interactive Charts

📋 Analysis Sections

🛠️ Development Tools

Available Commands

Testing & Quality

🌐 API Endpoints

GET / - Main Page

GET /health - Health Check

POST /generate - Generate Report

GET /reports?limit=10 - List Reports

⚙️ Configuration

🔐 API Security

Enabling API Key Protection

Using the Protected Endpoint

Backward Compatibility

Security Best Practices

📡 Data Sources

🌞 NOAA Space Weather Prediction Center

📊 N0NBH Solar Data API

🌍 SIDC (Solar Influences Data Analysis Center)

🌞 Helioviewer Project

🏗️ Project Structure

🚀 Production Deployment

🤝 Contributing

Development Guidelines

📄 License

📞 Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`GET /` - Main Page

`GET /health` - Health Check

`POST /generate` - Generate Report

`GET /reports?limit=10` - List Reports

Packages