README
¶
Starter project template with Go, Kong (CLI), Koanf (config), chi, React, and TanStack (Router, Query, Store). This aims to make you able to quickly create awesome app without having to bother with the initial setup.
pnpm dlx tiged riipandi/tango myapp-name
[!NOTE] This project is a template I use for my personal use, so you may encounter bugs. Please review the release notes thoroughly before updating, as breaking changes can occur!
🏁 Quick Start
You will need Go >= 1.27, Node.js >= 24.21, PNPM >= 12.3,
and Docker >= 20.10 installed on your machine.
- Install Go toolchain binaries (lint, migrate, release):
task deps - Find and replace
tango,Tango, andMyApplicationstrings in the source files. - Install application dependencies:
pnpm install - Create env file for development:
cp .env.example .env.local - Start the local Postgres:
docker compose up -d pgsql - Generate application secrets:
task secrets:generate -- --apply - Run database migrations:
task db:migrate - Run the project in development mode:
task dev
Vite serves the frontend on :3000 and proxies /api/* to Go on :3080.
Go files are watched and auto-rebuilt.
Available tasks
| Command | Description |
|---|---|
task dev |
Vite dev server (:3000) + Go API server (:3080) |
task run |
Run the Go server directly (debug build) |
task build |
Build frontend + Go binary (single file) |
task start |
Run the production binary |
task db:migrate |
Run database migrations |
task test |
Run tests (frontend and backend) |
task lint |
Run all linters (Go + JS) |
Generate Certificates
# Generate local development certificates
mkdir -p storage/certs && mkcert
-key-file storage/certs/localhost_key.pem \
-cert-file storage/certs/localhost_crt.pem \
localhost 127.0.0.1 ::1 host.docker.internal \
"*.localhost.test"
# Install the local CA in the system trust store.
mkcert -install
🏗 Architecture
A modular monolith: one binary, features are self-contained modules.
| Path | Purpose |
|---|---|
cmd/launcher |
CLI entry (serve, db migrate, secrets) via Kong |
internal/kernel |
Module contract + registry (routes, middleware, start/stop) |
internal/registry |
Wires modules and shared dependencies |
internal/config |
Koanf layering: defaults ← env file ← system env ← flags |
internal/datastore |
Postgres pool, health, transactions |
internal/transport |
HTTP server, middleware, SPA serving |
internal/logger |
LogLayer logging incl. the task queue adapter |
modules/* |
Feature modules, each owning its schema and store |
internal/queue |
Built-in Postgres-backed in-process task queue (see below) |
pkg/*{crypto,jwtutils,responder}* |
Shared building blocks: secret crypto, JWT (jwx), response envelope |
pkg/testutils |
Test helpers: shared testcontainers Postgres |
database/migrations |
Goose SQL migrations, the single source of schema truth |
Typed identifiers (user_*, audit_*) come from go.jetify.com/typeid.
Task queue
Background jobs run on the built-in queue (internal/queue), owned by
tango and originally based on backlite (MIT): a type-safe,
Postgres-backed queue that executes inside the app process — no broker
needed. Queues are registered in the registry, tasks are plain Go types
encoded with encoding/json/v2, and the schema lives in
database/migrations/00010_create_queue_tables.sql (queue_tasks,
queue_tasks_completed).
Configuration via env (see .env.example):
| Key | Default | Description |
|---|---|---|
QUEUE_WORKERS |
4 |
Goroutines executing tasks concurrently |
QUEUE_RELEASE_AFTER |
300 |
Seconds before a stuck claimed task is retried |
QUEUE_CLEANUP_INTERVAL |
21600 |
Seconds between expired-task cleanups |
🚀 Deployment
Build the image with docker build -f deploy/Dockerfile . and read the
Deployment Guidelines for detailed documentation.
📚 References
- Choosing the Right Go Web Framework
- How To Structure A Golang Project
- What's the best way to do authentication in modern applications
🪪 License
Licensed under either of Apache License 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Copyrights in this project are retained by their contributors.
See the LICENSE-APACHE and LICENSE-MIT files for more information.
🤫 Psst! If you like my work you can support me via GitHub sponsors.
Directories
¶
| Path | Synopsis |
|---|---|
|
launcher
package launcher implements the application command line.
|
package launcher implements the application command line. |
|
Package database wraps pg_dump, pg_restore, and psql.
|
Package database wraps pg_dump, pg_restore, and psql. |
|
seeders
Package seeders builds database fixtures: the first-admin setup row and deterministic development users.
|
Package seeders builds database fixtures: the first-admin setup row and deterministic development users. |
|
internal
|
|
|
config
Package config loads runtime settings in layers; later layers win:
|
Package config loads runtime settings in layers; later layers win: |
|
datastore
Package datastore owns the Postgres pool, transactions, and health checks.
|
Package datastore owns the Postgres pool, transactions, and health checks. |
|
fetcher
Package fetcher provides the shared outbound HTTP client.
|
Package fetcher provides the shared outbound HTTP client. |
|
jobs
Package jobs defines queued email and recurring maintenance tasks.
|
Package jobs defines queued email and recurring maintenance tasks. |
|
logger
Package logger wires LogLayer to console or file sinks.
|
Package logger wires LogLayer to console or file sinks. |
|
mailer
Package mailer renders templates and sends transactional email over SMTP.
|
Package mailer renders templates and sends transactional email over SMTP. |
|
queue
Package queue provides the built-in, type-safe task queue backed by Postgres.
|
Package queue provides the built-in, type-safe task queue backed by Postgres. |
|
registry
Package registry wires feature modules and shared dependencies.
|
Package registry wires feature modules and shared dependencies. |
|
transport/middleware
RPC guards, by shape of the service they protect.
|
RPC guards, by shape of the service they protect. |
|
modules
|
|
|
admin/apiaccess
Package apiaccess manages machine authorization: API definitions with scopes and client grants.
|
Package apiaccess manages machine authorization: API definitions with scopes and client grants. |
|
admin/apikey
Package apikey issues machine credentials sent via the X-API-KEY header, with expiry and last-used tracking.
|
Package apikey issues machine credentials sent via the X-API-KEY header, with expiry and last-used tracking. |
|
admin/appconfig
Package appconfig serves public and admin configuration endpoints.
|
Package appconfig serves public and admin configuration endpoints. |
|
admin/auditlog
Package auditlog captures domain events and exposes them via HTTP.
|
Package auditlog captures domain events and exposes them via HTTP. |
|
admin/customclaim
Package customclaim manages per-user and per-group key/value claims injected into OIDC tokens.
|
Package customclaim manages per-user and per-group key/value claims injected into OIDC tokens. |
|
federation
Package federation is the optional identity provider surface for other systems (OIDC/OAuth 2.0, SCIM, discovery).
|
Package federation is the optional identity provider surface for other systems (OIDC/OAuth 2.0, SCIM, discovery). |
|
federation/discovery
Package discovery serves RFC 8615 endpoints: /.well-known/openid-configuration and /.well-known/jwks.json.
|
Package discovery serves RFC 8615 endpoints: /.well-known/openid-configuration and /.well-known/jwks.json. |
|
federation/jwks
Package jwks owns signing key material: generation, encrypted storage, rotation with overlap, and the JWKS key provider consumed by token issuance and the discovery endpoints.
|
Package jwks owns signing key material: generation, encrypted storage, rotation with overlap, and the JWKS key provider consumed by token issuance and the discovery endpoints. |
|
federation/oidc
Package oidc is the OpenID Connect / OAuth 2.0 provider surface: /authorize + PAR (root router), /api/oidc/token, userinfo, introspect, revoke, end_session.
|
Package oidc is the OpenID Connect / OAuth 2.0 provider surface: /authorize + PAR (root router), /api/oidc/token, userinfo, introspect, revoke, end_session. |
|
federation/scimsync
Package scimsync provisions users and groups to a remote SCIM server.
|
Package scimsync provisions users and groups to a remote SCIM server. |
|
identity
Package identity owns internal authn/authz: user accounts plus the features wired at the composition root.
|
Package identity owns internal authn/authz: user accounts plus the features wired at the composition root. |
|
identity/account
Package account covers profile management, credential lifecycle, and account state.
|
Package account covers profile management, credential lifecycle, and account state. |
|
identity/devicelogin
Package devicelogin implements the QR / cross-device sign-in flow: an anonymous device parks a short-lived request keyed by a short user code; a signed-in user approves or denies it; the waiting device long-polls the exchange until approved.
|
Package devicelogin implements the QR / cross-device sign-in flow: an anonymous device parks a short-lived request keyed by a short user code; a signed-in user approves or denies it; the waiting device long-polls the exchange until approved. |
|
identity/emailverification
Package emailverification verifies a user's email address via a single-use token (auth_tokens, purpose = email_verification).
|
Package emailverification verifies a user's email address via a single-use token (auth_tokens, purpose = email_verification). |
|
identity/onetimeaccess
Package onetimeaccess issues single-use sign-in tokens delivered by email: admins mint them per user; unauthenticated users may request one for their own address when the app policy allows.
|
Package onetimeaccess issues single-use sign-in tokens delivered by email: admins mint them per user; unauthenticated users may request one for their own address when the app policy allows. |
|
identity/password
Package password owns credential hashing and verification: one argon2id/scrypt hash per user (PHC format via pkg/crypto), plus the identity lookup used by the sign-in flow.
|
Package password owns credential hashing and verification: one argon2id/scrypt hash per user (PHC format via pkg/crypto), plus the identity lookup used by the sign-in flow. |
|
identity/session
Package session manages sign-in sessions: issue (cookie-backed opaque tokens), validate (sliding expiry), list, and revoke.
|
Package session manages sign-in sessions: issue (cookie-backed opaque tokens), validate (sliding expiry), list, and revoke. |
|
identity/signup
Package signup implements application-based self-service sign-up flows (create + approve) with rate-limited endpoints.
|
Package signup implements application-based self-service sign-up flows (create + approve) with rate-limited endpoints. |
|
identity/token
Package token owns the shared one-shot token store (public.auth_tokens): rows keyed by (user_id, purpose), SHA-256 hash at rest, single-use consumption with an expiry check.
|
Package token owns the shared one-shot token store (public.auth_tokens): rows keyed by (user_id, purpose), SHA-256 hash at rest, single-use consumption with an expiry check. |
|
identity/user
Package user is the mandatory accounts core: user entities, their CRUD surface, and persistence.
|
Package user is the mandatory accounts core: user entities, their CRUD surface, and persistence. |
|
identity/usergroup
Package usergroup groups users so OIDC client access can be granted in bulk.
|
Package usergroup groups users so OIDC client access can be granted in bulk. |
|
identity/webauthn
Package webauthn implements passkey sign-in: registration and assertion ceremonies via go-webauthn, credential storage, and the admin credential CRUD.
|
Package webauthn implements passkey sign-in: registration and assertion ceremonies via go-webauthn, credential storage, and the admin credential CRUD. |
|
webhook
Package webhook registers outbound endpoints, fans application events out to the subscribers of each event name, and records every delivery attempt.
|
Package webhook registers outbound endpoints, fans application events out to the subscribers of each event name, and records every delivery attempt. |
|
pkg
|
|
|
jwtutils
Package jwtutils signs and verifies JWTs with typed private claims.
|
Package jwtutils signs and verifies JWTs with typed private claims. |
|
responder
Package responder writes the standard API response envelope.
|
Package responder writes the standard API response envelope. |
|
testutils
Package testutils provides shared integration-test helpers.
|
Package testutils provides shared integration-test helpers. |
|
validate
Package validate decodes and validates request bodies.
|
Package validate decodes and validates request bodies. |
|
tools
|
|
|
swagger-md
command
|
|
Click to show internal directories.
Click to hide internal directories.