Contributing to HitKeep

HitKeep is an open-source project and contributions are welcome. This page covers the local development setup. The full CONTRIBUTING.md in the repository is the authoritative reference.

Prerequisites

Tool	Version	Purpose
Go	1.26+	Backend — compiles to the single binary
C toolchain (gcc/clang)	system	Required by DuckDB’s CGo bindings
Air	latest	Go live-reload — auto-recompile on file change
Node.js	24+ LTS	Angular dashboard (includes tracker snippet build)
npm	10+	Frontend package manager

Quick Setup

# Clone
git clone https://github.com/pascalebeier/hitkeep.git
cd hitkeep

# Install Air (Go live-reload)
go install github.com/air-verse/air@latest

# Install frontend dependencies
cd frontend/dashboard && npm install && cd ../..

# Start the full dev stack (backend + frontend, hot reload)
make dev

The Makefile runs Air (backend, port :8080) and ng serve (frontend, port :4200) in parallel. Open http://localhost:4200 to access the dashboard in dev mode. The Angular dev server proxies /api/* and /ingest to the Go backend automatically.

Backend Development (Go + Air)

Air watches *.go, *.sql, and template files. On any change, it recompiles and restarts the server in ~1–2 seconds.

# Backend only
make dev-backend

# Air is configured via .air.toml in the repo root
# Entrypoint: cmd/hitkeep/main.go
# Args injected by Air: -log-level=debug -dev=true

Environment:

export HITKEEP_JWT_SECRET=hitkeep-dev-jwt-secret
# Air injects this automatically via the Makefile

Frontend Development (Angular)

The dashboard is Angular v21 with PrimeNG and Tailwind CSS v4.

# Frontend only (Angular dev server with HMR)
make dev-frontend

# Or directly:
cd frontend/dashboard
npm start    # → ng serve → http://localhost:4200

Production Build

make build

This runs in order:

Builds the Angular dashboard (ng build --configuration production)
Minifies the tracker snippet (hk.js) via esbuild into the dashboard output
Copies the output to public/
Compiles the Go binary (which embeds public/)

Project Structure

hitkeep/
├── cmd/hitkeep/        # Entry point — boots the modular registry
│   ├── main.go
│   └── mod_*.go        # Module registrations (build-tag gated)
├── internal/
│   ├── modules/        # Feature modules (auth, analytics, ingest, ...)
│   ├── database/       # DuckDB store — all SQL queries
│   ├── server/         # HTTP server, middleware, shared handlers
│   └── worker/         # Background jobs (retention, rollups, reports)
├── frontend/
│   └── dashboard/      # Angular v21 SPA + tracker snippet (src/tracker/index.js)
├── public/             # Embedded static files (built frontend output)
├── scripts/            # Developer scripts
├── Makefile
└── .air.toml           # Air live-reload config

Commit Conventions

HitKeep uses Conventional Commits for automated changelog generation:

feat(scope): add new feature
fix(scope): fix a bug
chore(deps): update dependency
docs: update contributing guide

Types: feat, fix, chore, docs, refactor, test, perf

Submitting a Pull Request

Fork the repository, create a branch from main
Write your change following existing patterns
Run go test ./... and verify the frontend builds
Commit with a Conventional Commit message
Open a PR against main with a clear description

Reporting Issues

Bugs / feature requests: GitHub Issues
Security vulnerabilities: GitHub Security Advisories