README
¶
Beach
A hypermedia-first, server-rendered web framework for Go, with an entity component system for realtime app state.
git clone https://github.com/ThirdCoastInteractive/Beach
go get github.com/ThirdCoastInteractive/Beach
Stack (non-negotiable): net/http · templ · Datastar (free core) · Tailwind v4 +
rybitten · pgx · sqlc · goose · Postgres LISTEN/NOTIFY · SSE · custom ecs engine ·
WebSocket via vendored coder/websocket for the non-hypermedia channel
(RFC 05).
Hypermedia-first. Server-driven. The first paint is the final paint. Boring in the good way.
Docs
Start at the docs index — it holds the overall diagrams (realtime spine, package dependencies) and links every sub-document:
- RFC — charter, scope (packages + framework laws), the ECS pitch, WebSockets, accessibility.
- Architecture — module layout (per
go.dev/doc/modules/layout), boot spine, the
root
beachpackage + handler shapes, hub, cache/session/i18n, theuitoolkit (templ views, the driftwood kit, 14KB rule, deferred sections), the component catalog +ui/specimen, theecsengine, thesim, lifecycles, tooling, auth (argon2id + RBAC), API codegen, analytics (chart— SSR SVG, 22 types, client interaction layer — +chClickHouse), RYB color & gamut theming (rybitten), and the example apps (boardwalk / driftbottle / pantry / booking-manager).
Module
github.com/ThirdCoastInteractive/Beach. Default branch is main.
Agents
This repo is meant to be used by coding agents. Start at AGENTS.md.
Skills live under skills/ (beach, beach-ui, beach-a11y, beach-test).
beach new stamps an AGENTS.md into a new app.
Examples
make up-pantry # CRUD / apigen / auth / charts
make up-driftbottle # hub / SSE matchmaking
make up-boardwalk # sim / ecs + snapshot
make up-booking-manager # mailer / sms
Each example mounts the driftwood specimen at /specimen.
Status
The framework, the four example apps, and the tooling compile, test, and serve (see the docs index).
Views are .templ components compiled by templ generate (a Go tool — see the
tool directive in go.mod). Run make gen after editing any .templ or CSS
file; it runs go tool templ generate and rebuilds app.css. Generated
*_templ.go files are committed, so plain go build works on a fresh clone.
make build / make vet / make test all depend on gen.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
beach
command
Command beach is Beach's scaffold CLI.
|
Command beach is Beach's scaffold CLI. |
|
beach-apigen
command
Command beach-apigen is a sqlc process plugin that reads six annotations on named SQL queries and emits beach handler wiring — PageFunc/ActionFunc factories, route registration, and the NOTIFY trigger migration.
|
Command beach-apigen is a sqlc process plugin that reads six annotations on named SQL queries and emits beach handler wiring — PageFunc/ActionFunc factories, route registration, and the NOTIFY trigger migration. |
|
beach-geogen
command
beach-geogen generates pkg/chart/geodata_gen.go from the Natural Earth 1:110m TopoJSON files embedded under data/.
|
beach-geogen generates pkg/chart/geodata_gen.go from the Natural Earth 1:110m TopoJSON files embedded under data/. |
|
beach-palette
command
Command beach-palette derives the framework's color tokens and writes them into the Tailwind input stylesheet.
|
Command beach-palette derives the framework's color tokens and writes them into the Tailwind input stylesheet. |
|
beach-vet
command
Command beach-vet runs Beach lint analyzers over a source tree and prints findings.
|
Command beach-vet runs Beach lint analyzers over a source tree and prints findings. |
|
examples/boardwalk
command
Command boardwalk is a sim/ecs + persistence + analytics showcase of Beach's stack: a Monopoly-style real-estate game where the whole live slice — player positions, cash, turn order, property ownership — lives in an ecs.Store owned by a single-writer sim loop, mutated by commands, and pushed to every watcher over SSE via hub projections.
|
Command boardwalk is a sim/ecs + persistence + analytics showcase of Beach's stack: a Monopoly-style real-estate game where the whole live slice — player positions, cash, turn order, property ownership — lives in an ecs.Store owned by a single-writer sim loop, mutated by commands, and pushed to every watcher over SSE via hub projections. |
|
examples/boardwalk/internal/analytics
Package analytics is the game's ClickHouse action firehose and the /stats widgets over it.
|
Package analytics is the game's ClickHouse action firehose and the /stats widgets over it. |
|
examples/boardwalk/internal/store
Package store is boardwalk's Postgres persistence lane: a single row holding the latest CBOR snapshot of the ecs.Store.
|
Package store is boardwalk's Postgres persistence lane: a single row holding the latest CBOR snapshot of the ecs.Store. |
|
examples/boardwalk/internal/web
Package web is boardwalk's HTTP surface: the page/action handlers, the SSE stream handlers, and the templ views they render.
|
Package web is boardwalk's HTTP surface: the page/action handlers, the SSE stream handlers, and the templ views they render. |
|
examples/booking-manager
command
Command booking-manager is Beach's small-operator showcase: a self-hostable manager for a handful of seasonal rentals (cottages, cabins, getaways).
|
Command booking-manager is Beach's small-operator showcase: a self-hostable manager for a handful of seasonal rentals (cottages, cabins, getaways). |
|
examples/booking-manager/internal/locks
Package locks is booking-manager's smart-lock integration boundary.
|
Package locks is booking-manager's smart-lock integration boundary. |
|
examples/booking-manager/internal/notify
Package notify sends booking-manager's guest messages: an acknowledgement when an inquiry arrives and a confirmation (with the door code) when a booking is confirmed.
|
Package notify sends booking-manager's guest messages: an acknowledgement when an inquiry arrives and a confirmation (with the door code) when a booking is confirmed. |
|
examples/booking-manager/internal/store
Package store is booking-manager's Postgres-backed system of record: properties and their key codes, guest inquiries and bookings, the staffing suite (applicants, staff, shifts, time entries), and supply inventory.
|
Package store is booking-manager's Postgres-backed system of record: properties and their key codes, guest inquiries and bookings, the staffing suite (applicants, staff, shifts, time entries), and supply inventory. |
|
examples/booking-manager/internal/web
Package web is booking-manager's HTTP surface: the app DI container plus every page, action, and the login flow.
|
Package web is booking-manager's HTTP surface: the app DI container plus every page, action, and the login flow. |
|
examples/driftbottle
command
Boot configuration for driftbottle.
|
Boot configuration for driftbottle. |
|
examples/driftbottle/internal/analytics
Package analytics is driftbottle's off-the-hot-path persistence and analytics.
|
Package analytics is driftbottle's off-the-hot-path persistence and analytics. |
|
examples/driftbottle/internal/chat
Package chat is driftbottle's LIVE stranger-chat core: the in-memory matchmaking state machine, the per-pair rolling feed, moderation, and the HTTP+SSE handlers that drive it.
|
Package chat is driftbottle's LIVE stranger-chat core: the in-memory matchmaking state machine, the per-pair rolling feed, moderation, and the HTTP+SSE handlers that drive it. |
|
examples/driftbottle/internal/sockets
Package sockets is driftbottle's WebSocket demo surface (RFC 05): the non-hypermedia channel next door to the SSE fan-out the rest of the app benchmarks.
|
Package sockets is driftbottle's WebSocket demo surface (RFC 05): the non-hypermedia channel next door to the SSE fan-out the rest of the app benchmarks. |
|
examples/pantry
command
Command pantry is Beach's CRUD / apigen / auth / analytics showcase: an at-home grocery ERP.
|
Command pantry is Beach's CRUD / apigen / auth / analytics showcase: an at-home grocery ERP. |
|
examples/pantry/internal/analytics
Package analytics is pantry's ClickHouse activity firehose.
|
Package analytics is pantry's ClickHouse activity firehose. |
|
examples/pantry/internal/store
Package store is pantry's Postgres-backed system of record: inventory, storage locations, and shopping lists.
|
Package store is pantry's Postgres-backed system of record: inventory, storage locations, and shopping lists. |
|
examples/pantry/internal/web
Package web is pantry's HTTP surface: the app DI container plus every page, widget, action, and the login flow.
|
Package web is pantry's HTTP surface: the app DI container plus every page, widget, action, and the login flow. |
|
internal
|
|
|
deps
Package deps anchors the module's external dependencies so go.mod stays stable while the rest of the framework is built in parallel.
|
Package deps anchors the module's external dependencies so go.mod stays stable while the rest of the framework is built in parallel. |
|
lint
Package lint holds the beach vet analyzers: static checks that enforce Beach's house rules over a Go source tree.
|
Package lint holds the beach vet analyzers: static checks that enforce Beach's house rules over a Go source tree. |
|
pkg
|
|
|
auth
Package auth is the identity layer: the Principal, the hardened login flow, and a deliberately small RBAC.
|
Package auth is the identity layer: the Principal, the hardened login flow, and a deliberately small RBAC. |
|
beach
Package beach is Beach's HTTP layer: the framework's front door.
|
Package beach is Beach's HTTP layer: the framework's front door. |
|
beach/view
Package view owns the framework's own front-end source: the Tailwind input stylesheet under css/ and the compiled, served tree under static/.
|
Package view owns the framework's own front-end source: the Tailwind input stylesheet under css/ and the compiled, served tree under static/. |
|
cache
Package cache provides two in-process cache shapes and the NOTIFY-driven invalidation that wires them to Postgres.
|
Package cache provides two in-process cache shapes and the NOTIFY-driven invalidation that wires them to Postgres. |
|
ch
Package ch is the framework's ClickHouse client: native-protocol connection, goose migrations, a generic non-blocking ingest batcher, and a typed query helper.
|
Package ch is the framework's ClickHouse client: native-protocol connection, goose migrations, a generic non-blocking ingest batcher, and a typed query helper. |
|
chart
Package chart computes SVG geometry for server-rendered charts.
|
Package chart computes SVG geometry for server-rendered charts. |
|
color
Package color is Beach's color math: OKLCH, sRGB, and the WCAG contrast the framework's palette is derived under.
|
Package color is Beach's color math: OKLCH, sRGB, and the WCAG contrast the framework's palette is derived under. |
|
config
Package config loads typed application configuration from the environment.
|
Package config loads typed application configuration from the environment. |
|
consent
Package consent is the first-party cookie-preference record.
|
Package consent is the first-party cookie-preference record. |
|
datastar
Package datastar is the only sanctioned way to emit Datastar data-* attributes and to open a server-sent event stream inside Beach.
|
Package datastar is the only sanctioned way to emit Datastar data-* attributes and to open a server-sent event stream inside Beach. |
|
ecs
Package ecs is a standalone, zero-knowledge archetype ECS: entities and columnar (struct-of-arrays) component storage with tick-stamped change detection, typed queries, CBOR snapshots, and entity-valued relationships.
|
Package ecs is a standalone, zero-knowledge archetype ECS: entities and columnar (struct-of-arrays) component storage with tick-stamped change detection, typed queries, CBOR snapshots, and entity-valued relationships. |
|
hub
Package hub is an in-memory topic fan-out for realtime SSE surfaces.
|
Package hub is an in-memory topic fan-out for realtime SSE surfaces. |
|
i18n
Package i18n is Beach's flat-key translation runtime.
|
Package i18n is Beach's flat-key translation runtime. |
|
mailer
Package mailer sends transactional email behind one small interface: build an Email, hand it to a Mailer, and let configuration pick the wire.
|
Package mailer sends transactional email behind one small interface: build an Email, hand it to a Mailer, and let configuration pick the wire. |
|
md
Package md renders Markdown to sanitized HTML.
|
Package md renders Markdown to sanitized HTML. |
|
passwords
Package passwords provides argon2id password hashing in the PHC string format, built directly on golang.org/x/crypto/argon2 with zero dependencies beyond x/crypto.
|
Package passwords provides argon2id password hashing in the PHC string format, built directly on golang.org/x/crypto/argon2 with zero dependencies beyond x/crypto. |
|
pg
Package pg is the boot spine for everything Postgres-connection-shaped: the pool, migrations, transactions, and LISTEN/NOTIFY.
|
Package pg is the boot spine for everything Postgres-connection-shaped: the pool, migrations, transactions, and LISTEN/NOTIFY. |
|
prefs
Package prefs carries a visitor's answer to "may this page keep changing on its own?" from the request that resolved it to the view that has to obey it.
|
Package prefs carries a visitor's answer to "may this page keep changing on its own?" from the request that resolved it to the view that has to obey it. |
|
quantity
Package quantity is Beach's typed value-with-unit system: a domain- agnostic way to carry a measured value together with the unit it arrived in.
|
Package quantity is Beach's typed value-with-unit system: a domain- agnostic way to carry a measured value together with the unit it arrived in. |
|
rybitten
Package rybitten ports meodai's RYBitten (https://rybitten.space) to Go: a pseudo-RYB color model derived from Johannes Itten's chromatic circle.
|
Package rybitten ports meodai's RYBitten (https://rybitten.space) to Go: a pseudo-RYB color model derived from Johannes Itten's chromatic circle. |
|
session
Package session is the Postgres-backed session store with auth middleware.
|
Package session is the Postgres-backed session store with auth middleware. |
|
sim
Package sim runs a simulation over an ecs.Store: a single goroutine owns the store, drives a fixed tick loop, drains a typed command channel at the top of each tick, runs systems in registration order, then projects the tick's dirty component set onto hub topics as pre-rendered patches.
|
Package sim runs a simulation over an ecs.Store: a single goroutine owns the store, drives a fixed tick loop, drains a typed command channel at the top of each tick, runs systems in registration order, then projects the tick's dirty component set onto hub topics as pre-rendered patches. |
|
sms
Package sms sends transactional text messages behind one small interface: build a Message, hand it to a Sender, and let configuration pick the wire.
|
Package sms sends transactional text messages behind one small interface: build a Message, hand it to a Sender, and let configuration pick the wire. |
|
storage
Package storage is the framework's unified file store: one Store interface, swappable backends.
|
Package storage is the framework's unified file store: one Store interface, swappable backends. |
|
storage/cfimages
Package cfimages is a small client for Cloudflare Images — the hosted, paid product that stores originals and serves resized variants from imagedelivery.net.
|
Package cfimages is a small client for Cloudflare Images — the hosted, paid product that stores originals and serves resized variants from imagedelivery.net. |
|
storage/cfstream
Package cfstream is a small client for Cloudflare Stream — the hosted video product that accepts tus resumable uploads and serves playback from cloudflarestream.com / videodelivery.net.
|
Package cfstream is a small client for Cloudflare Stream — the hosted video product that accepts tus resumable uploads and serves playback from cloudflarestream.com / videodelivery.net. |
|
storage/s3
Package s3 is a storage.Store over any S3-compatible object store.
|
Package s3 is a storage.Store over any S3-compatible object store. |
|
theme
Package theme derives Beach's design tokens — every colour the kit paints, in both a light and a dark scheme — from a short list of parameters.
|
Package theme derives Beach's design tokens — every colour the kit paints, in both a light and a dark scheme — from a short list of parameters. |
|
ui
templ: version: v0.3.1020
|
templ: version: v0.3.1020 |
|
ui/driftwood
templ: version: v0.3.1020
|
templ: version: v0.3.1020 |
|
ui/specimen
Package specimen is the framework's living showcase: one (intentionally over-budget) page that renders the token sheet, the icon set, every driftwood component in its states, the rybitten gamut strips, and every chart type with representative data.
|
Package specimen is the framework's living showcase: one (intentionally over-budget) page that renders the token sheet, the icon set, every driftwood component in its states, the rybitten gamut strips, and every chart type with representative data. |
Click to show internal directories.
Click to hide internal directories.