Skip to content

README.md

Latest commit

 

History

History
172 lines (136 loc) · 6.99 KB

README.md

File metadata and controls

172 lines (136 loc) · 6.99 KB
Raw

Ticked - HatMax Reference Example

Single-binary todo list application demonstrating HatMax framework patterns with authentication, event-driven architecture, and Postgres-based pub/sub.

A todo list is the archetypical example for a reason: it's familiar, simple to understand, and lets us focus on the framework patterns rather than complex business logic.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                       Single Binary :8080                       │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │    Auth     │  │    List     │  │   Admin     │              │
│  │   Handler   │  │   Handler   │  │   Handler   │              │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
│         │                │                │                     │
│         ▼                ▼                ▼                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │    Auth     │  │    List     │  │   Admin     │              │
│  │   Service   │  │   Service   │  │   Service   │              │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
│         │                │                │                     │
│         │                │ publish        │                     │
│         │                ▼                │                     │
│         │         ┌─────────────┐         │                     │
│         │         │   PubSub    │─────────┼──────┐              │
│         │         │  (NOTIFY)   │         │      │ subscribe    │
│         │         └──────┬──────┘         │      ▼              │
│         │                │                │ ┌─────────────┐     │
│         │                │                │ │   Audit     │     │
│         │                │                │ │   Service   │     │
│         │                │                │ └──────┬──────┘     │
│         │                │                │        │            │
│         └────────────────┼────────────────┴────────┘            │
│                          ▼                                      │
│                   ┌─────────────┐                               │
│                   │    sqlc     │  Type-safe queries            │
│                   └──────┬──────┘                               │
└──────────────────────────┼──────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                        PostgreSQL                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │    auth     │  │   ticked    │  │    audit    │              │
│  │   schema    │  │   schema    │  │   schema    │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
└─────────────────────────────────────────────────────────────────┘

Patterns Demonstrated

  • Single Binary: All features compile to one executable with embedded assets
  • HTML + HTMX: Server-side rendering with dynamic interactions
  • Postgres PubSub: Domain events via LISTEN/NOTIFY (no external broker)
  • Store Pattern: Type-safe queries with sqlc
  • Lifecycle Management: Automatic component discovery via app.Setup()
  • Feature-based Organization: Code organized under internal/feat/

Prerequisites

  • Go 1.24+
  • PostgreSQL running locally
  • Make
  • sqlc (for regenerating queries)

Quick Start

1. Setup PostgreSQL

Create database and user:

createdb ticked
createuser -P dev  # password: dev

2. Run migrations

make migrate

3. Build and run

make run

Access the application at http://localhost:8080

Available Commands

Application

make build      # Build the binary
make run        # Build and run
make clean      # Remove binary and logs

Database

make migrate    # Run database migrations
make sqlc       # Regenerate sqlc queries

Development

make test       # Run tests

Configuration

Default configuration in config.yaml:

server:
  port: ":8080"

database:
  host: localhost
  port: 5432
  user: dev
  password: dev
  database: tickedhm
  sslmode: disable

log:
  level: debug

Override with environment variables (prefix TICKED_):

TICKED_SERVER_PORT=:9000 make run
TICKED_DATABASE_HOST=db.example.com make run

API Endpoints

Routes follow CQRS-light pattern: verb-noun style, GET for queries, POST for commands.

Auth

  • GET /signup - Signup page
  • POST /signup - Register user
  • GET /signin - Login page
  • POST /signin - Authenticate user
  • POST /signout - Logout

List

  • GET /list-items - Todo list view
  • POST /add-item - Add item
  • POST /toggle-item - Toggle item completion
  • POST /delete-item - Delete item

Admin

  • GET /admin - Dashboard
  • GET /admin/list-users - Users list
  • GET /admin/get-user?id=xxx - User details
  • POST /admin/update-roles - Update user roles
  • POST /admin/toggle-user - Toggle user active status
  • GET /admin/list-events - Audit events

Use GET /debug/routes to list all registered endpoints.