Heat - Pedal to the Metal Companion

This is a fan-made, digital "side-along" companion app for the Heat: Pedal to the Metal board game. It is designed to enhance your tabletop experience by providing real-time race tracking, championship management, and interactive map visualization.

🏁 Board Game Companion Features

🏎️ Racer Tracking - Keep track of all players' positions and status on the board.
🗺️ Interactive Maps - Use official-style GeoJSON tracks or upload a photo of your own game board to use as a background.
🤖 AI Board Extraction - (Alpha) Snap a photo of your board and let the AI attempt to trace the track spaces for digital tracking.
📊 Championship Management - Automated points calculation and historical record-keeping across multiple race seasons.
⚡ Digital Dashboard - A live, synchronized view for all players to see gaps, rankings, and fastest laps.
📈 Statistics & Analytics - Advanced stats including head-to-head comparisons, points progression charts, streaks, ELO ratings, and CSV export.

🚀 Quick Start

# Clone and setup
git clone <repository-url>
cd heat

# Install dependencies
go mod download

# Build
CGO_ENABLED=1 go build -o heat-server .

# Run
./heat-server

Open http://localhost:6270 in your browser.

📋 Prerequisites

Component	Version	Notes
Go	1.21+	Backend runtime
SQLite3	-	Development libraries required
GCC	-	For CGO compilation
Docker	20.10+	Optional, for containerized deployment
Docker Compose	1.29+	Optional

Linux Installation

sudo apt-get update
sudo apt-get install -y build-essential libsqlite3-dev

macOS Installation

# With Homebrew
brew install go sqlite3
xcode-select --install

🏗️ Project Structure

.
├── main.go               # Application entry point & route setup
├── main_test.go          # Integration tests
├── paths_test.go         # Path configuration tests
├── go.mod / go.sum       # Go module definition
├── heat.db               # SQLite database (created at runtime)
├── Dockerfile            # Multi-stage Docker build
├── docker-compose.yml    # Docker Compose orchestration
├── Taskfile.yml          # Task runner
├── app/                  # Application state (DB, sessions, globals)
│   └── app.go
├── db/                   # Database initialization & migrations
│   └── db.go
├── handlers/             # HTTP handlers by domain
│   ├── auth.go           # Login, logout, setup
│   ├── racers.go         # Racer CRUD
│   ├── race.go           # Race info & history
│   ├── tracks.go         # Track CRUD & AI extraction
│   ├── upload.go         # File upload & management
│   ├── quotes.go         # Quote management
│   ├── settings.go       # AI, email, notification, Umami settings
│   ├── email.go          # Email sending & racer emails
│   └── stats.go          # Statistics & analytics
├── middleware/            # HTTP middleware
│   └── middleware.go      # Auth, rate limiting, security headers, Umami
├── models/               # Data structures
│   └── models.go
├── ws/                   # WebSocket broadcasting
│   └── ws.go
├── static/               # Frontend assets
│   ├── index.html        # Main web interface
│   ├── admin.html        # Admin dashboard
│   ├── controller.html   # Race controller view
│   ├── stats.html        # Statistics view
│   ├── chat.html         # Commentary chat
│   ├── style.css         # Styling
│   └── js/               # Compiled TypeScript
├── ts/                   # TypeScript source
└── tests/                # Playwright e2e tests

🔌 API Endpoints

Race Management

Method	Endpoint	Auth	Description
`GET`	`/api/racers`	No	List all racers
`POST`	`/api/racers`	Yes	Create/update a racer
`DELETE`	`/api/racers`	Yes	Delete a racer
`GET`	`/api/race-info`	No	Get current race info
`POST`	`/api/race-info`	Yes	Update race info
`GET`	`/api/race-history`	No	Get race history (season or oneoff)
`POST`	`/api/race-history`	Yes	Save a race result to history
`DELETE`	`/api/race-history`	Yes	Delete a race history entry
`GET`	`/api/oneoff-races`	No	Get one-off (non-season) races
`DELETE`	`/api/oneoff-races`	Yes	Delete a one-off race

Track Management

Method	Endpoint	Auth	Description
`GET`	`/api/tracks`	No	List all tracks
`POST`	`/api/tracks`	Yes	Create/update a track
`DELETE`	`/api/tracks`	Yes	Delete a track
`POST`	`/api/tracks/ai-extract`	Yes	AI track extraction from image

Statistics & Analytics

Method	Endpoint	Auth	Description
`GET`	`/api/racer-stats`	No	Get racer career statistics
`POST`	`/api/racer-stats`	Yes	Update racer statistics manually
`GET`	`/api/track-stats`	No	Get per-track statistics (wins, races, fastest laps)
`GET`	`/api/stats/head-to-head`	No	Head-to-head comparison between two racers
`GET`	`/api/stats/points-progression`	No	Cumulative points progression over a season
`GET`	`/api/stats/streaks`	No	Win, podium, and DNF streaks for all racers
`GET`	`/api/stats/elo`	No	ELO-style ratings based on race results
`GET`	`/api/stats/export`	No	Export all racer stats as CSV
`GET`	`/api/stats/track-performance`	No	Per-track performance breakdown by racer

Settings & Admin

Method	Endpoint	Auth	Description
`POST`	`/api/login`	No*	Login or create admin account
`POST`	`/api/logout`	No	Logout and clear session
`GET`	`/api/check-setup`	No	Check if admin is configured
`GET`	`/api/ai-settings`	Yes	Get AI extraction settings
`POST`	`/api/ai-settings`	Yes	Update AI extraction settings
`GET`	`/api/notification-settings`	Yes	Get Gotify notification settings
`POST`	`/api/notification-settings`	Yes	Update notification settings
`POST`	`/api/test-notification`	Yes	Send a test notification
`GET`	`/api/email-settings`	Yes	Get SMTP email settings
`POST`	`/api/email-settings`	Yes	Update SMTP email settings
`GET`	`/api/racer-emails`	Yes	Get racer email addresses
`POST`	`/api/racer-emails`	Yes	Save a racer's email address
`POST`	`/api/send-race-email`	Yes	Manually send race results email
`GET`	`/api/umami-settings`	Yes	Get Umami analytics settings
`POST`	`/api/umami-settings`	Yes	Update Umami settings

Media & Content

Method	Endpoint	Auth	Description
`GET`	`/api/uploads`	No	List recent file uploads
`POST`	`/api/upload`	Yes	Upload an image file
`GET`	`/api/quotes`	No	List all quotes
`POST`	`/api/quotes`	Yes	Add a new quote
`PUT`	`/api/quotes`	Yes	Update a quote
`DELETE`	`/api/quotes`	Yes	Delete a quote
`GET`	`/api/quote/random`	No	Get a random quote

System

Method	Endpoint	Auth	Description
`GET`	`/api/version`	No	Get application version
`GET`	`/ws`	No	WebSocket endpoint for live race updates
`GET`	`/docs`	No	Swagger UI documentation
`GET`	`/api-docs`	No	OpenAPI spec (JSON)

* Login endpoint requires setup flag for initial admin creation. After setup, standard credentials required.

📈 Statistics & Analytics

Head-to-Head Comparison

Compare two racers across all season races they've both participated in:

GET /api/stats/head-to-head?racer1=1&racer2=2

Returns total races together, wins per racer, and average finishing positions.

Points Progression

Track cumulative points growth for any racer across a season:

GET /api/stats/points-progression?racer_id=1

Returns an ordered array of cumulative points after each race, suitable for line charts.

Streaks

See which racers have the longest active and all-time streaks:

GET /api/stats/streaks

Tracks three streak types per racer:

wins - Consecutive 1st place finishes
podiums - Consecutive top-3 finishes
dnf - Consecutive Did Not Finish results

ELO Ratings

ELO-style skill ratings computed from all pairwise race results:

GET /api/stats/elo

Uses K=32 with 1500 starting rating. Each race creates pairwise comparisons between every two racers. Ratings update after each race and are sorted descending.

Export to CSV

Download all racer statistics as a CSV file:

GET /api/stats/export

Returns a CSV file with columns: ID, Name, Car, Points, Rank, Races, Wins, Gold, Silver, Bronze, Fastest Laps, DNF, DNS.

Track Performance Breakdown

Analyze performance per track:

GET /api/stats/track-performance           # Overview of all tracks
GET /api/stats/track-performance?racer_id=1 # Per-racer track breakdown

Without racer_id: returns track summaries with unique driver counts. With racer_id: returns wins, podiums, races, and average finishing position per track for that racer.

🐳 Docker Deployment

Build Image

docker build -t heat-server .

Run with Docker Compose

# Start the application
docker-compose up -d

# View logs
docker-compose logs -f heat-server

# Stop the application
docker-compose down

The application will be available at http://localhost:6270

Data Persistence

Local: Database stored as heat.db in the working directory; images in static/images
Docker: Database stored in heat-db volume at /db/heat.db; images in heat-data volume at /app/images

To remove persistent data:

docker-compose down -v

🛠️ Development

# Stop current container
docker-compose down

# Rebuild and start
docker-compose build && docker-compose up -d

⚠️ Troubleshooting

Build Errors

Error	Solution
`no C compiler found`	Install build essentials: `sudo apt-get install build-essential`
`sqlite3.h not found`	Install dev packages: `sudo apt-get install libsqlite3-dev`

Runtime Errors

Issue	Solution
Port 6270 in use	Change port in `docker-compose.yml`
Database locked	Ensure only one instance is running

📄 License

MIT License - see LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 392 Commits
.github		.github
.opencode		.opencode
app		app
db		db
docs		docs
ent		ent
handlers		handlers
media/8e		media/8e
middleware		middleware
models		models
openspec		openspec
pkg/logger		pkg/logger
racing		racing
static		static
tests		tests
ts		ts
ws		ws
.gitignore		.gitignore
.releaserc.yaml		.releaserc.yaml
00_test_auth_test.go		00_test_auth_test.go
01_test_unit_test.go		01_test_unit_test.go
02_test_racers_test.go		02_test_racers_test.go
04_test_race_test.go		04_test_race_test.go
05_test_stats_test.go		05_test_stats_test.go
06_test_tracks_quotes_teams_test.go		06_test_tracks_quotes_teams_test.go
07_test_settings_seasons_test.go		07_test_settings_seasons_test.go
08_test_api_test.go		08_test_api_test.go
09_test_infrastructure_test.go		09_test_infrastructure_test.go
30_test_crud_test.go		30_test_crud_test.go
90_test_htmx_test.go		90_test_htmx_test.go
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
Taskfile.yml		Taskfile.yml
build.mjs		build.mjs
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
main.go		main.go
package-lock.json		package-lock.json
package.json		package.json
paths_test.go		paths_test.go
playwright.config.ts		playwright.config.ts
renovate.json		renovate.json
telemetry.go		telemetry.go
testhelpers_test.go		testhelpers_test.go
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Heat - Pedal to the Metal Companion

🏁 Board Game Companion Features

🚀 Quick Start

📋 Prerequisites

Linux Installation

macOS Installation

🏗️ Project Structure

🔌 API Endpoints

Race Management

Track Management

Statistics & Analytics

Settings & Admin

Media & Content

System

📈 Statistics & Analytics

Head-to-Head Comparison

Points Progression

Streaks

ELO Ratings

Export to CSV

Track Performance Breakdown

🐳 Docker Deployment

Build Image

Run with Docker Compose

Data Persistence

🛠️ Development

⚠️ Troubleshooting

Build Errors

Runtime Errors

📄 License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 105

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages