README
¶
C4Stack
C4Stack is a Go module of building blocks for small web apps on one European stack: Go, Gin, Templ, HTMX and PostgreSQL, with Hanko for sign-in, Creem for payments and Scaleway for email. A generator creates new apps that pin a C4Stack release, so fixes and new features reach them with one command.
The app owns its main, routes, layout and configuration. C4Stack provides the parts
that are hard to get right: sign-in and account deletion, browser and API security,
API keys, a prepaid credit ledger with payment webhooks, migrations, health checks and
graceful shutdown.
C4Stack is an independent open-source project by @coolapso. Coolapso, the company behind Searchbase Cloud, builds its products on it. C4Stack grew out of Searchbase Cloud, and its tests prove that Searchbase's database moves onto it in one release, without moving or copying data.
Quickstart
You need Go 1.26 or later, Task 3.53.1 or later, Docker, and a
Hanko Cloud project with http://localhost:8080 as its app URL.
go install github.com/coolapso/c4stack/cmd/c4stack@latest
c4stack new acme --module example.com/acme
cd acme # put your Hanko API URL in .env
task db:up db:migrate
task dev # http://localhost:8080
Modules
| Package | Purpose |
|---|---|
web |
Gin engine with security middleware, CSRF, an extensible CSP, health endpoints and graceful shutdown |
app |
The command entry point: serve, migrate and operator commands |
ui |
The default design, layout types and content-hashed assets |
identity, identity/hanko |
The identity provider interface and the Hanko adapter, with profile management |
accounts |
Accounts linked by verified email, sign-in middleware, settings and account deletion |
apikeys |
Opt-in API keys with bearer authentication and a keys page |
payments, payments/creem |
The payment provider interface and the Creem adapter |
credits |
Opt-in prepaid credit: ledger, holds, purchases, webhooks and history |
credits/expiry |
Opt-in expiry of unused credit, after a delivered warning |
email, email/scaleway |
The email sender interface and the Scaleway adapter |
Docs
- Guide: recipes for pages, tables, API endpoints, holds, design, providers, upgrades and tasks
- Operations: configuration, deployment, health, migrations and runbooks
- Architecture: packages, extension points and design decisions
- Credits contract: ledger rules and webhook outcomes
- Releases, with notes generated from the commits
- Textlab: an example app that uses every module
Status
C4Stack is young, and opinionated: it is the stack Coolapso builds its own products on. From v0.1.0, the public packages change only by addition and released migrations never change. Each release's notes list its behaviour changes and migrations. Not in scope lists what C4Stack leaves out on purpose.
Contributing and security
Bug reports and fixes are welcome. CONTRIBUTING.md explains how, including the Contributor License Agreement. Report vulnerabilities privately, as SECURITY.md describes.
Want help building on C4Stack? Coolapso offers consulting: coolapso.sh.
Developing C4Stack
task check # vet, lint, formatting, tidiness and generated code
task test # unit tests
task test:integration # with a disposable PostgreSQL
task test:app # generate the starter app and serve it end to end
task test:upgrade # move a generated app to the next release
task test:example # the example app, with browser tests
task serve # run the example app on http://localhost:8082
task serve starts the example's database, migrates it, and serves with live reload.
When the server stops, it stops the database too, keeping its data. It fetches the Creem
test keys from the maintainer's Infisical project, so it needs the infisical CLI,
logged in, with access to that project. Without it, run the example with its own .env,
as its README describes.
Releases are the owner's: task release:full runs every check above, then semrel tags
the next version and publishes its GitHub release. Maintaining
covers repository settings, security reports and releases.
License
C4Stack is licensed under the Apache License 2.0, copyright 2026 Carlos Colaço (coolapso). Bundled third-party files keep their own licenses; NOTICE lists them.
The starter files that c4stack new writes into your app are yours: use, change and
license them as you like, without attribution.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package accounts maps identities to local accounts, protects signed-in routes and deletes accounts.
|
Package accounts maps identities to local accounts, protects signed-in routes and deletes accounts. |
|
Package apikeys issues API keys to accounts and authenticates API requests with them.
|
Package apikeys issues API keys to accounts and authenticates API requests with them. |
|
Package app is the entry point of a C4Stack application.
|
Package app is the entry point of a C4Stack application. |
|
apptest
Package apptest gives integration tests an App on a fresh, disposable database.
|
Package apptest gives integration tests an App on a fresh, disposable database. |
|
cmd
|
|
|
c4stack
command
Command c4stack generates new C4Stack apps.
|
Command c4stack generates new C4Stack apps. |
|
Package credits keeps prepaid credit for accounts: a ledger, purchases through a payment provider, and the charges the app makes for its work.
|
Package credits keeps prepaid credit for accounts: a ledger, purchases through a payment provider, and the charges the app makes for its work. |
|
expiry
Package expiry expires credit that has gone unused, after warning its owner.
|
Package expiry expires credit that has gone unused, after warning its owner. |
|
Package email defines the transactional email sender interface.
|
Package email defines the transactional email sender interface. |
|
scaleway
Package scaleway sends email through Scaleway Transactional Email.
|
Package scaleway sends email through Scaleway Transactional Email. |
|
Package identity defines the identity provider interface.
|
Package identity defines the identity provider interface. |
|
hanko
Package hanko is the Hanko identity provider adapter.
|
Package hanko is the Hanko identity provider adapter. |
|
internal
|
|
|
postgres
Package postgres connects to PostgreSQL and applies namespaced migrations.
|
Package postgres connects to PostgreSQL and applies namespaced migrations. |
|
scaffold
Package scaffold generates a new C4Stack app.
|
Package scaffold generates a new C4Stack app. |
|
testdb
Package testdb creates disposable databases for integration tests.
|
Package testdb creates disposable databases for integration tests. |
|
Package payments defines the payment provider interface the credits module uses: a hosted checkout for a server-priced amount, and verified webhook events.
|
Package payments defines the payment provider interface the credits module uses: a hosted checkout for a server-priced amount, and verified webhook events. |
|
creem
Package creem is the Creem payment provider adapter.
|
Package creem is the Creem payment provider adapter. |
|
templ: version: v0.3.1070
|
templ: version: v0.3.1070 |
|
Package web provides a Gin engine with the security middleware C4Stack apps share: request IDs and logging, safe panic recovery, a host check, security headers with an extensible Content Security Policy, body limits and CSRF protection.
|
Package web provides a Gin engine with the security middleware C4Stack apps share: request IDs and logging, safe panic recovery, a host check, security headers with an extensible Content Security Policy, body limits and CSRF protection. |