The User Guide explains how a Hatmax web application is composed. Read it in order to build a working mental model of the application before consulting individual package contracts or focused procedures. Use that model through the recommended conversational TUI, the supported headless CLI, or direct Go development.
This guide is not a step-by-step project tutorial. It uses small, connected examples to explain responsibilities and assembly. A separate tutorial will later build a complete Todo application.
The guide assumes familiarity with Go, HTTP, HTML, and relational databases. It does not assume previous Hatmax experience.
Hatmax is intended for server-rendered Go applications that use explicit dependency wiring, HTMX for targeted interaction, and Postgres-first infrastructure. The guide treats those choices as one application model, not as a menu of interchangeable frameworks.
The journey follows the order in which an application is understood and designed:
- Orientation defines the kind of application Hatmax supports and the boundary between Hatmax and application-owned behavior.
- Application Anatomy maps the entrypoint, application components, features, infrastructure, templates, and tests.
- Lifecycle and Wiring explains how dependencies become an ordered, running process.
- The Request Boundary follows an HTTP request through middleware and routing.
- Pages and Partials connects templates, rendering, and HTMX responses.
- Forms and Validation places request, field, domain, and persistence validation at their correct boundaries.
- Presentation Primitives covers UI helpers, modals, formatting, pagination, and internationalization.
- Feature Anatomy connects model, store, service, handler, templates, wiring, and tests as one canonical feature.
- Persistence and Migrations explains the Postgres lifecycle and schema ownership.
- Models and Data Flow follows application data across feature layers.
- Identity and Sessions adds authentication, authorization, and cryptographic support.
- Configuration and Runtime Settings separates startup configuration, logging, and mutable settings.
- Events and Background Work introduces pubsub and scheduled work.
- Application Services places mail, images, telemetry, and replaceable adapters.
- Testing and Evolution explains how to validate and safely extend the assembled application.
- Assisted Generation teaches the recommended conversational TUI and presents the headless CLI as a supported alternative for focused work.
After this journey, you should be able to read a Hatmax composition root, locate feature and infrastructure ownership, follow a request and its data through every boundary, place new behavior in the canonical vertical slice, and select tests that prove the resulting contracts.
The guide establishes that application model before assisted generation on purpose. Generated changes remain reviewable ordinary Go, SQL, templates, and explicit wiring; the same architectural understanding applies whether a change is written manually or proposed by Hatmax.
- Use the How-to Guides for focused procedures.
- Use the Reference for exact APIs, configuration, limits, and behavior.
- Use Explanation for design rationale and tradeoffs.
- Use the Package Map to locate a specific Hatmax capability.