tracks

Tracks

⚡ Go, fast. A batteries included toolkit for hypermedia servers

Docs · Status · Vision · Roadmap · Documentation · License

Current Status

Phase 0 (Foundation) is complete! 🎉

The Tracks CLI tool is ready to generate production-ready Go web applications. Install it now and start building.

What works now:

• ✅ CLI infrastructure (complete)
  • Root command with version, help, and global flags
  • Renderer pattern (Console, JSON, TUI-ready)
  • Mode detection (TTY, CI, flags, env vars)
  • Theme system with Lip Gloss styling
  • Comprehensive test coverage (unit + integration + Docker E2E)
• ✅ Project generation (tracks new command)
  • Production-ready project scaffolding
  • Choice of database drivers (LibSQL, SQLite3, PostgreSQL)
  • Clean architecture with layered structure (handlers → services → repositories)
  • Auto-generated .env with sensible defaults
  • Health check endpoint with repository pattern
  • Cross-platform support (Linux, macOS, Windows)
• ✅ Complete development tooling
  • Makefile with comprehensive targets (dev, test, lint, build, generate-mocks)
  • Docker Compose for all database drivers (auto-started with make dev)
  • Air for live reload during development
  • golangci-lint configuration for code quality
  • Mockery integration for automatic mock generation
  • SQLC integration for type-safe database code
  • GitHub Actions CI workflow (tests on Ubuntu, macOS, Windows)
• ✅ Comprehensive documentation
  • Live documentation site with guides and tutorials
  • Architecture overview and layer-by-layer guide
  • CLI reference with examples
  • Testing strategies and patterns
  • Installation guides for all platforms

Quick Start

Install Tracks and create your first project:

# Install (requires Go 1.25+)
go install github.com/anomalousventures/tracks/cmd/tracks@latest

# Create a new project
tracks new myapp

# Start development (auto-starts Docker services and generates .env)
cd myapp
make dev    # Auto-starts required services, starts server with live reload

# Verify health endpoint
curl http://localhost:8080/api/health

What you get:

• Production-ready project structure with clean layered architecture
• Health check endpoint with database connectivity test
• Complete development tooling (Makefile, Air live reload, golangci-lint)
• Docker Compose for local development (auto-started with make dev)
• Mockery for automatic test mock generation
• SQLC for type-safe database queries
• Auto-generated .env with sensible defaults
• GitHub Actions CI workflow ready to use
• All tests passing out of the box

See the CLI documentation and Getting Started guide for detailed instructions.

Coming next:

• Phase 1 (In Progress): Code generation (resources, handlers, services)
  • ✅ Epic 1.3 Phase 1 Complete: Basic asset infrastructure (web/ directory, embed.FS, static file handler)
  • 🚧 Next: TailwindCSS, JavaScript bundling, HTMX v2
• Phase 2: Authentication and authorization
• See Roadmap for details

Vision

Tracks will be a code-generating web framework for Go that produces idiomatic, production-ready applications. Built for developers who want the productivity of modern frameworks with the performance and simplicity of Go.

Design Principles

Type-Safe Everything

• templ for compile-time HTML safety
• SQLC generates type-safe Go from SQL
• No runtime reflection in generated code

Hypermedia-First

• HTMX integration for dynamic UIs without JavaScript
• Server-rendered templates with progressive enhancement
• RESTful URL patterns with hypermedia (HTML) responses, not JSON APIs

Idiomatic Go

• Generated code looks hand-written by an experienced Go developer
• Standard library patterns and clear error handling
• Dependency injection via interfaces for easy testing

Batteries Included

• Authentication (magic links, OTP, OAuth)
• Authorization (Casbin RBAC)
• Observability (OpenTelemetry)
• Development tooling (hot reload, linting, CI/CD templates)

Roadmap

Tracks development is organized into 7 phases. See docs/roadmap for detailed plans.

Phase 0: Foundation ✅ Complete

Goal: Working CLI that generates project scaffolds

Completed Epics:

1. ✅ CLI Infrastructure - Cobra framework, Renderer pattern, version tracking
2. ✅ Template Engine - Embed system for project templates
3. ✅ Project Generation - tracks new command
4. ✅ Generated Project Tooling - Makefiles, Air, linting, Docker, CI/CD, Mockery, SQLC
5. ✅ Documentation - Installation guides, tutorials, architecture docs

Status: Complete · Released: v0.1.0

Future Phases

• Phase 1 (Current): Core Web Layer - Chi router, handlers, middleware, templ templates
• Phase 2: Database Layer - SQLC, Goose migrations, LibSQL/PostgreSQL support
• Phase 3: Authentication - Magic links, OTP, OAuth providers
• Phase 4: Interactive TUI - Bubble Tea interface for generators
• Phase 5: Production - OpenTelemetry, health checks, deployment
• Phase 6: Authorization - Casbin RBAC
• Phase 7: Advanced Features - Real-time, file uploads, background jobs

View Full Roadmap →

Documentation

Live Documentation

📚 View Full Documentation →

The complete documentation site includes guides, tutorials, API references, and examples.

Product Requirements

Detailed PRD documents describe the complete vision:

• Summary - Overview and goals
• Core Architecture - Application structure and patterns
• Database Layer - SQLC, migrations, and query patterns
• Authentication - Magic links, OTP, and OAuth
• Authorization (RBAC) - Casbin integration
• Code Generation - Generator design and CLI commands
• Testing Strategy - Unit, integration, and E2E testing
• Deployment - Production deployment strategies

Development

For contributors:

• CONTRIBUTING.md - Development setup and coding standards
• Roadmap - Phase breakdown and epic details
• GitHub Issues - Task tracking

Running Tests

Tracks uses a multi-layered testing approach for maximum cross-platform coverage:

make test                            # Unit tests (fast, all platforms)
go test ./tests/integration          # Integration tests (all platforms)
go test -tags=docker ./tests/integration  # Docker E2E tests (Ubuntu only)
make test-coverage                   # All tests with coverage reports

Test Types:

• Unit Tests - Colocated with source, run with -short flag, use race detector
• Integration Tests - File generation, validation, git operations (no external services)
• Docker E2E Tests - Full end-to-end with databases (Postgres, LibSQL) via Docker Compose

Docker E2E tests use the //go:build docker tag and only run on Ubuntu in CI due to Docker setup complexity on macOS/Windows. Non-Docker tests run on all platforms.

See Testing Strategy PRD for complete details.

Philosophy

Idiomatic Go

Tracks generates code that looks like it was hand-written by an experienced Go developer:

• No magic or reflection in generated code
• Standard library patterns and interfaces
• Explicit error handling with context
• Interface-based design for testability

Type Safety

Type safety catches errors at compile time:

• templ templates are type-checked Go code
• SQLC generates Go structs and functions from SQL
• No string-based query building or SQL injection risks
• DTOs with field-level validation

Hypermedia-First

HTMX enables rich interactions without JavaScript complexity:

• Server renders HTML with templ templates
• HTMX provides dynamic UI updates via HTML over the wire
• Progressive enhancement with Alpine.js where needed
• RESTful URL patterns with hypermedia (HTML) responses, not JSON APIs

Convention Over Configuration

Sensible defaults with escape hatches:

• Standard project structure and file organization
• Generators follow consistent patterns
• Override defaults when needed
• .tracks.yaml for CLI metadata (committed), .env for runtime config (secrets)
• Hierarchical config: defaults → .env → environment variables

Technology Stack

Router: Chi - lightweight, idiomatic HTTP router Templates: templ - type-safe HTML templates compiled to Go Database: SQLC - generates type-safe Go from SQL queries Migrations: Goose - version-controlled database migrations Auth: Custom + OAuth providers (Google, GitHub, etc.) Authorization: Casbin - role-based access control Frontend: HTMX + Alpine.js + TailwindCSS (optional) Observability: OpenTelemetry - tracing, metrics, and logs Logging: zerolog - structured JSON logging Testing: Standard library + testify for assertions CLI/TUI: Cobra + Bubble Tea (Charm stack) Development: Docker Compose - local service orchestration

Project Status

Tracks is in pre-alpha development (Phase 1). The API and generated code structure may change significantly before v1.0.

Not ready for production use. Follow development progress via GitHub Issues and Roadmap.

Contributing

Contributions are welcome! The project is in active early development.

Ways to contribute:

• Report bugs and request features via GitHub Issues
• Discuss ideas in GitHub Discussions
• Submit pull requests (see CONTRIBUTING.md for development setup)

License

Tracks is released under the MIT License.

Acknowledgments

Tracks builds on excellent open-source projects:

• Chi - HTTP routing
• templ - Type-safe templates
• SQLC - SQL code generation
• Casbin - Authorization framework
• Goose - Database migrations
• Bubble Tea - TUI framework
• Cobra - CLI framework

An Anomalous Venture by Aaron Ross