Contributing to HitKeep

HitKeep's easiest contributor setup only needs Docker with Docker Compose support. The dev Compose stack runs the Go backend, Air live reload, Angular, Mailpit, and seeded demo data in containers.

The repository's CONTRIBUTING.md remains the detailed checklist. This page gives the maintained first-run path.

Quick Setup

git clone https://github.com/pascalebeier/hitkeep.git
cd hitkeep
make dev-docker-seed

Open http://localhost:4200 and sign in with:

demo@example.com
demo1234

The Docker stack starts:

Service	URL or port	Purpose
Backend	`http://localhost:8080`	Go API and ingest server with Air live reload
Frontend	`http://localhost:4200`	Angular dev server with hot reload
Mailpit	`http://localhost:8025`	Local inbox for invites, password resets, reports, and magic links

If your environment does not have make, run the same workflow with Docker Compose:

docker compose -f compose.dev.yaml run --rm seed
docker compose -f compose.dev.yaml up --build backend frontend mailpit

Daily Commands

# Start the Docker dev stack without reseeding
make dev-docker

# Seed demo data, then start the Docker dev stack
make dev-docker-seed

# Stop dev containers
make dev-docker-down

# Remove dev containers and volumes
make dev-docker-clean

make dev-docker-clean removes the Docker volumes that hold the dev database, Go caches, npm cache, and node_modules.

Native Development

Native dev is still available if you prefer to run tools on your host. Install:

Tool	Version	Purpose
Go	1.26+	Backend build and pinned Go tools
C toolchain	system default	DuckDB CGo bindings
Node.js and npm	24+	Angular dashboard and tracker build
Mailpit	latest	Local SMTP inbox

Air is pinned in the repository and runs through go tool air. You do not need a global Air install.

# Start Mailpit in another terminal
mailpit

# Seed demo data, then start backend and frontend
make dev-seed

Open http://localhost:4200. The Angular dev server proxies /api/* and /ingest to the Go backend on :8080.

Backend Development

make dev-backend

Air is configured by .air.toml in the repository root. It watches *.go, *.sql, *.html, *.tpl, and *.tmpl files, then rebuilds ./cmd/hitkeep/main.go and runs the binary with -log-level=debug.

The native backend target defaults mail to Mailpit on localhost:1025 with no TLS. The Docker backend target uses the mailpit service on the Compose network.

Frontend Development

The dashboard uses Angular 21, PrimeNG, and Tailwind CSS 4.

make dev-frontend

Or run it directly:

cd frontend/dashboard
npm start

The Docker frontend service uses proxy.conf.docker.json so requests from the browser-facing Angular dev server reach the backend container.

Production Build

make build

This builds the Angular dashboard, minifies the tracker snippets, copies the dashboard output to public/, and compiles the Go binary that embeds those files.

Verification And Tests

Run the checks that match your change before opening a pull request:

# Backend
go test ./...
go test -race ./...
golangci-lint run

# Frontend
cd frontend/dashboard
npm run fmt:check
npm run lint
npm run test -- --watch=false --no-progress

For browser-level verification, use the Angular CLI entrypoint:

cd frontend/dashboard
npx playwright install --with-deps chromium
npm run e2e

npm run e2e builds the production dashboard bundle, builds the Go binary, seeds realistic demo data, starts a disposable HitKeep instance, and runs the browser journeys against the real app.

For focused iteration:

cd frontend/dashboard
npm run test:e2e -- e2e/auth.seeded.spec.js --workers=1

For deployment smoke checks:

cd frontend/dashboard
npm run test:e2e:smoke
npm run test:e2e:smoke:subdirectory

Project Structure

hitkeep/
├── cmd/
│   ├── hitkeep/        # Runtime entry point
│   └── seed/           # Local and demo data seeding
├── internal/
│   ├── database/       # DuckDB stores and SQL queries
│   ├── server/         # HTTP server, middleware, and handlers
│   ├── ingest/         # In-process ingest consumers
│   └── worker/         # Background workers
├── frontend/
│   └── dashboard/      # Angular dashboard and tracker snippets
├── public/             # Embedded static files from the dashboard build
├── scripts/            # Developer and release scripts
├── tests/              # E2E launchers, fixtures, and test harnesses
├── compose.dev.yaml    # Docker hot-reload development stack
├── 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

Common scopes include analytics, events, tracker, api, auth, teams, cloud, frontend, docs, seed, screenshots, ci, and github.

Submitting A Pull Request

Fork the repository and create a branch from main.
Write your change following existing patterns.
Run the relevant backend, frontend, and browser verification.
Commit with a Conventional Commit message.
Open a pull request against main with a clear description and testing notes.

For repository-specific details and the latest contributor checklist, see the root CONTRIBUTING.md.