These names are the vocabulary for the User Guide and the reference. The contracts they point at are documented in later reference pages. The implementation notes remain in the package readmes.
Hatmax is a composable Go toolkit. An application wires Hatmax packages together. Hatmax does not require a hidden global registry for that wiring.
A component is a value passed to app.Setup. Setup keeps the capabilities
the value actually implements:
StartablehasStart(context.Context) error.app.Startcalls it during startup.StoppablehasStop(context.Context) error. Shutdown calls every collected stop function. Startup rollback calls stop functions by their position in the independent stop slice.RouteRegistrarhasRegisterRoutes.app.Startcalls it after every start function has succeeded.
A component may implement any subset of these interfaces. The implementation note is app/readme.md.
app.Start runs start functions in the order app.Setup collected them. If
one start function returns an error at index i, Hatmax calls stop functions
from index i-1 to zero and returns the start error. Routes are registered
only after every start function succeeds.
The start and stop slices are collected independently. Rollback represents the already-started components only when each ordered startup component also contributes a stop function. Hatmax does not provide a database transaction or an unconditional all-or-nothing startup guarantee.
Static configuration is the config.Config value loaded at process start.
config.Load reads a file, an environment prefix, and arguments.
Config.Validate checks that value before the application uses it. The
loaded value does not change while the process is running.
The implementation note is config/readme.md.
Settings are runtime key-value configuration. A Schema declares the key,
the type, and the validation rule. A Registry holds those schemas. A
Store reads and writes values. Service returns the stored value, or the
schema default when the store has no value.
Settings are not config.Config. Changing a setting does not reload the
static configuration.
The implementation note is settings/readme.md.
The database pool, the Postgres pubsub implementation, and the Postgres
scheduler backend are components passed through app.Setup. Auth sessions
are persisted through the auth Queries interface. The usual implementation
of that interface is Postgres.
Those services do not require Redis or a separate message broker. Replacing
one of them means passing a different component, or a different Queries
implementation, into application setup.
A package readme.md sits next to the package. It shows usage for that
package. It is the implementation note.
The reference states the contract without the usage walkthrough. The User Guide teaches one step of an application and links to the reference for the exact contract.