README
¶
GHAT(D)
GHAT(D) is an open-source, opinionated, and free full-stack web application foundation based on the Go programming language. Its name is an acronym that stands for Go, HTMX, Alpine.js, Tailwind, and DaisyUI, which originally formed the foundational stack. Over time, for improved usability, it has also been extended to support most Vite-compatible front-end stacks (tested with Vue). The aim is to make GHAT(D) a solid base for creating highly portable, scalable, and performant full-stack projects. Whether you need just a backend, a landing page, or a content-driven application, you can still utilise GHAT(D) without committing to a hidden application container.
We recognise that everyone has unique needs, and ideally their solutions should not start with a messy foundation that requires cleaning up before building. To reduce cognitive load and make preparation easier, we have introduced "building blocks" which we call Details. A Detail is an independent application that can function both within a GHAT(D) project and on its own. GHAT(D) supports api, web, and web-vite Detail types.
Motivation
GHAT(D) is a hobby project I work on in my spare time. It is designed to provide a friendly starting point for people like me who are interested in Go, APIs, and web applications, and who want a consistent foundation and shared standards to build from. I hope GHAT(D) can serve as an ejectable base for many awesome projects and initiatives.
I also aim to use this project as a learning opportunity, to improve my understanding of and share my knowledge of lightweight frontend libraries, highly portable full-stack alternatives, and cost-effective infrastructure solutions for full-scale products.
As we develop this project, I want to also create tutorials/guides for those who want to integrate it with other technologies, such as rpc, graphql, websocket, and others.
I am a platform engineer by trade, so I do not promise perfect code by any stretch of the imagination (especially with the front end - so please support and contribute). Instead, I am aspiring to create a standardised project base that helps those curious (about Go, APIs, hobby projects, and web app development) to turn their ideas/ hobbies into tangible product(s) that they can demo and even ship.
This will be an exciting experience, and I look forward to building out this project with you all and sharing my progress and knowledge as it matures.
Core Packages
GHAT(D) offers modular packages that can be used both together and independently. Our goal is for each package to adhere to clean architecture principles, featuring comprehensive documentation and examples. We are committed to implementing these practices in both new and legacy packages, especially those that are less extensible for other projects.
Authentication & Verification
A dual-channel verification system providing both magic link and human-readable code entry.
- Access Manager - Complete authentication and authorisation with email-based verification, login, OAuth, and API token management
accessmanager- User creation, login, registration, email verification, OAuth, API token managementaccessmanager/middleware- JWT, API token, rate-limiting, and hardened code-verification middlewareaccessmanager/helpers- Context-transmission utilities and unique code generationauth- JWT creation, validation, and metadata extractionapitoken- API token lifecycle management
Email System
A complete email solution split into three composable packages for maximum flexibility and testability.
- Email Manager - Complete email system with templating, sending, and audit logging
emailtemplater- Generate HTML email templates with variable substitutionemailprovider- Abstract email sending across providers (SparkPost, logging, custom)emailmanager- High-level orchestration with audit integration
Billing System
A complete billing solution split into three composable packages for maximum flexibility and testability.
- Billing Manager - Complete billing system with webhook processing, subscription management, and audit logging
paymentprovider- Abstract payment provider webhook verification and payload normalisation (Stripe, Lemon Squeezy, Ko-fi)billing- Manage subscription and billing event data persistence with repository patternbillingmanager- High-level orchestration with webhook processing and audit integration
- Pricer - Source-of-truth pricing catalog with plans, feature entitlements, provider refs, Mongo migrations, and pricing-card E2E fixtures
pricer- Manage pricing plans, costs, features, and provider-linked catalog metadata
Additional Packages
- Audit - Handles audit logging for compliance and debugging
- Content Manager - HTTP orchestration for CMS-style content
- Group - User groups, memberships, and hierarchical organisations
- Logger - Structured logging with middleware support
- MongoDB Migrator - Shared migration command with host-owned registrations and templates
- Notifier - Push notification registration, preferences, and delivery
- Observability - Provider-neutral OpenTelemetry traces, metrics, and logs
- Post - Reusable content models, persistence, and publication rules
- Reminder - User-owned scheduled reminders with target-based lookups and execution tracking
- Router - Shared HTTP routing and route attachment
- SEO - Sitemap generation and persistence
- SPA - Single-page application serving and fallback routing
- Streaker - Generic idempotent streak completions, current/best stats, and history listing
- Repository - MongoDB repository patterns and utilities
- Server - Ejectable HTTP server lifecycle helper with graceful shutdown
- Starter/v0 - Ejectable lazy composition layer for GHATD application wiring
- User v2 - Configurable universal user model and persistence
- User Manager - User-facing orchestration across user, group, reminder, and related services
- Vision - Feedback and roadmap management
- Error Manifest - Cross-package error mapping and bundle composition Note on Core Packages: This is a curated overview rather than an exhaustive package inventory. Each documented package keeps its canonical README alongside the package code.
Dual-Channel Verification
GHAT(D) supports a dual-channel verification flow for login and email verification — users receive both a magic link (with a JWT token) and an 8-character alphanumeric code in the same email.
How It Works
- Email delivery: Both login and verification emails contain a clickable magic link AND a human-readable 8-character code displayed in large monospaced font.
- Link flow (
?t=<jwt-token>): User clicks the magic link → token is validated → user is authenticated. - Code flow (
?c=ABCD1234): User enters the code in the app or web interface ("I already have a session code") → code is resolved to its corresponding token via ephemeral storage → token is validated → user is authenticated. - Code generation: Each code is globally unique (A-Z, 0-9), crypto-random, stored in ephemeral storage with a TTL matching the token expiry, and regenerated on collision.
Security Measures
| Layer | Mechanism |
|---|---|
| Code entropy | 8-character A-Z/0-9 = ~2.8 trillion combinations |
| Collision resistance | Ephemeral storage check with up to 5 retry attempts |
| Brute-force protection | HardenedRateLimitProtection middleware tracks attempts per IP and per code within a configurable window (default: 5/hr per IP, 5/hr per code) |
| Auto-blocking | IPs exceeding the threshold are temporarily blocked (default: 1 hour) |
| One-time use | Codes and tokens are invalidated after successful verification |
| Time-bounded | Login tokens default to 5 minutes; email-verification tokens default to 10 minutes |
| Refresh rotation tolerance | Near-concurrent duplicate refreshes can reuse the winning rotation result instead of consuming the same refresh token twice |
| Login email cooldown | Duplicate login email sends for the same active user/context are suppressed during a short cooldown window |
| Audit logging | All verification attempts (pass and fail) and rate-limit blocks are logged for monitoring |
| Rate-limit response | Blocked IPs receive HTTP 429 with EPH0-002 — no information leakage |
Starting locally
Before getting started please make sure you have the correct version of Go installed or you can use asdf to install the pinned toolchain from .tool-versions. Minimum required Go version: 1.26.4.
# Add the plugin for Go
asdf plugin add golang
# Install the pinned version
asdf install
Use asdf exec when running maintenance commands so local validation uses the same Go toolchain as the repository:
asdf exec go test ./...
asdf exec go run golang.org/x/vuln/cmd/govulncheck@v1.3.0 ./...
asdf exec go mod tidy
Using the CLI (experimental)
Run the source version of the CLI with the repository's pinned toolchain:
asdf exec go run cli/cli.go --help
Inspect a command before using it:
asdf exec go run cli/cli.go <desired-command> --help
The new command can assemble a host application from one or more Details, but the generator remains experimental and its defaults may target development branches or module versions. Review the generated application and run asdf exec go mod tidy before relying on it. Generated applications include a host-owned cmd/mongo-migrator adapter and migrations/mongo/template.go; the adapter keeps using GHATD's shared migration implementation while its host imports are rewritten to the new module.
Example local command:
asdf exec go run cli/cli.go new \
-n "awesome-service" \
-m "github.com/example/awesome-service" \
-w "github.com/example/ghatd-detail-api"
See About Details and Getting Started With A New Project for the supported Detail types and generated-app workflow. See Managing MongoDB Migrations before adding or applying migrations.
Starting the server
To start the server you can use the code:
asdf exec go run main.go start-server
For a better development experience, install reflex to rerun the server command when files change:
reflex -r '\.(html|go|css|png|svg|ico|js|woff2|woff|ttf|eot)$' -s -- asdf exec go run main.go start-server
Good to know
ASCII Art
All ASCII art in this template was created using PatorJK.
Curl Examples
- Making a
GETrequest:curl -i -X GET "http://localhost:4000/v0/health/check"
How to stop file server showing directory listing?
Add a blank index.html file to the specific directory that you want to disable listings for. For example, the code below will create an index file which will stop the web app from showing and listing page.
touch internal/web/ui/static/index.html
Hot reloading
Install reflex
asdf exec go install github.com/cespare/reflex@latest
You can find more information in the repo https://github.com/cespare/reflex
Once installed, run the server
reflex -r '\.(html|go|css|png|svg|ico|js|woff2|woff|ttf|eot)$' -s -- asdf exec go run main.go start-server
How to build binaries
One of the benefits of using the GHATD stack is that it compiles everything into a single binary. This makes it highly portable and provides numerous deployment options.
CLI
To build a binary for the GHATDCLI for your desired system architecture, please follow the instructions below:
All commands should be executed from the root directory.
export BINARY_NAME=ghatdcli
CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 asdf exec go build -a -installsuffix cgo -ldflags="-w -s" -o ./$BINARY_NAME cli/cli.go
export BINARY_NAME=ghatdcli
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 asdf exec go build -a -installsuffix cgo -ldflags="-w -s" -o ./$BINARY_NAME cli/cli.go
export BINARY_NAME=ghatdcli
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 asdf exec go build -a -installsuffix cgo -ldflags="-w -s" -o ./$BINARY_NAME cli/cli.go
export BINARY_NAME=ghatdcli
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 asdf exec go build -a -installsuffix cgo -ldflags="-w -s" -o ./$BINARY_NAME cli/cli.go
Web App
To build a binary for web app to your desired system architecture, please follow the instructions below:
All commands should be executed from the root directory.
export BINARY_NAME=ghatd
CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 asdf exec go build -a -installsuffix cgo -ldflags="-w -s" -o ./$BINARY_NAME main.go
export BINARY_NAME=ghatd
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 asdf exec go build -a -installsuffix cgo -ldflags="-w -s" -o ./$BINARY_NAME main.go
export BINARY_NAME=ghatd
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 asdf exec go build -a -installsuffix cgo -ldflags="-w -s" -o ./$BINARY_NAME main.go
export BINARY_NAME=ghatd
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 asdf exec go build -a -installsuffix cgo -ldflags="-w -s" -o ./$BINARY_NAME main.go
License
This project is licensed under the MIT License.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
mongo-migrator
Package migrator connects a host application's migration registrations to GHAT(D)'s shared MongoDB migrator command.
|
Package migrator connects a host application's migration registrations to GHAT(D)'s shared MongoDB migrator command. |
|
examples
|
|
|
observability
command
The observability example runs an HTTP service or a standalone worker with shared telemetry lifecycle and no external application dependencies.
|
The observability example runs an HTTP service or a standalone worker with shared telemetry lifecycle and no external application dependencies. |
|
external
|
|
|
accessmanager/helpers
Package accessmanagerhelpers provides request-context helpers shared by authentication middleware and downstream request handlers.
|
Package accessmanagerhelpers provides request-context helpers shared by authentication middleware and downstream request handlers. |
|
auth
Package auth implements JWT token signing, verification, and authentication services.
|
Package auth implements JWT token signing, verification, and authentication services. |
|
billing
Package billing implements subscription and billing management functionality.
|
Package billing implements subscription and billing management functionality. |
|
contacter
Package contacter implements contact management functionality for managing user contacts, addresses, and communication preferences.
|
Package contacter implements contact management functionality for managing user contacts, addresses, and communication preferences. |
|
emailmanager
Package emailmanager provides email sending functionality with template support and integration with various email service providers.
|
Package emailmanager provides email sending functionality with template support and integration with various email service providers. |
|
errormanifest
Package errormanifest provides a reusable Composer for building []reply.ErrorManifest slices with explicit layering and last-wins semantics.
|
Package errormanifest provides a reusable Composer for building []reply.ErrorManifest slices with explicit layering and last-wins semantics. |
|
errormanifest/bundles
Package bundles provides reusable error manifest bundles for common GHATD composition paths.
|
Package bundles provides reusable error manifest bundles for common GHATD composition paths. |
|
group
Package group implements a universal group management system supporting teams, organizations, projects, and other hierarchical groupings.
|
Package group implements a universal group management system supporting teams, organizations, projects, and other hierarchical groupings. |
|
group/examples
command
|
|
|
http/server
Package server provides helpers for running HTTP servers with graceful shutdown.
|
Package server provides helpers for running HTTP servers with graceful shutdown. |
|
logger
Package logger provides an interface for managing structured logging via a context.Context.
|
Package logger provides an interface for managing structured logging via a context.Context. |
|
migrator/mongo
Package mongo provides the shared MongoDB migration command used by GHAT(D) host applications.
|
Package mongo provides the shared MongoDB migration command used by GHAT(D) host applications. |
|
notifier
Package notifier manages the devices, addresses, and preferences that make up the GHATD notification system.
|
Package notifier manages the devices, addresses, and preferences that make up the GHATD notification system. |
|
notifier/migrations
Package migrations contains MongoDB index setup for the notifier package.
|
Package migrations contains MongoDB index setup for the notifier package. |
|
observability
Package observability provides shared, provider-neutral telemetry helpers.
|
Package observability provides shared, provider-neutral telemetry helpers. |
|
observability/otelcobra
Package otelcobra supplies telemetry lifecycle for executable Cobra actions.
|
Package otelcobra supplies telemetry lifecycle for executable Cobra actions. |
|
observability/otelhttp
Package otelhttp composes GHATD's HTTP telemetry, request logger, and recovery middleware into a single outer handler for a complete router.
|
Package otelhttp composes GHATD's HTTP telemetry, request logger, and recovery middleware into a single outer handler for a complete router. |
|
paymentprovider/helpers
Package helpers centralises safe host-application configuration for payment providers.
|
Package helpers centralises safe host-application configuration for payment providers. |
|
policy
Package policy implements a policy management service for web applications.
|
Package policy implements a policy management service for web applications. |
|
reminder
Package reminder manages user reminder declarations and execution tracking.
|
Package reminder manages user reminder declarations and execution tracking. |
|
repository
Package repository provides a flexible MongoDB repository implementation with built-in logging, error handling, and common database operations.
|
Package repository provides a flexible MongoDB repository implementation with built-in logging, error handling, and common database operations. |
|
router/routecontext
Package routecontext shares matched route templates with middleware outside a router, without matching requests a second time or collecting raw paths.
|
Package routecontext shares matched route templates with middleware outside a router, without matching requests a second time or collecting raw paths. |
|
starter/v0
Package starter provides an ejectable Lazy composition layer over modular GHATD packages.
|
Package starter provides an ejectable Lazy composition layer over modular GHATD packages. |
|
validator
Package validator provides input validation functionality for request data validation across the application.
|
Package validator provides input validation functionality for request data validation across the application. |
|
internal
|
|
|
migrations
|
|
|
testing
|
|