Business management software: a Postgres + Go backend with a TypeScript/React front end, shipped as a single static binary that embeds the built SPA.
cmd/server/ main entry point (HTTP server + migration-on-startup)
internal/ the backend's domain packages: config, db, httpapi,
master, documents, orders, posting, reporting, banking,
pdf, printing, auth
db/migrations/ ordered SQL migrations (see db/README.md)
db/seed/ reference-data seeds (ISO countries/currencies)
web/ the TypeScript/React front end (see docs/frontend-stack.md)
e2e/ browser-driven UI tests (Playwright; see docs/e2e-testing.md)
spec/ stack-neutral specification of the API and business rules
conformance/ black-box, stdlib-only test suite for any implementation of spec/
tools/ dependencies.py writes dependencies.json; measure.py reports metrics from it (docs/counterpart-metrics.md)
deploy/ deployment assets for the fixed-price VPS
docs/ architecture, deployment, and development docs
vendor/ all third-party Go source, committed and reviewable
- Go 1.25.11 (pinned in
go.modvia thetoolchaindirective) - Postgres 16 or 17 reachable via
DATABASE_URL(the deployment box runs Debian 13's Postgres 17; the suite passes on both)
| Env var | Required | Default | Purpose |
|---|---|---|---|
DATABASE_URL |
yes | — | Postgres connection string |
HTTP_ADDR |
no | :8080 |
HTTP listen address |
PORT |
no | — | Listen port; overrides HTTP_ADDR when set (Cloud Run injects it) |
TEST_DATABASE_URL |
for tests | — | Database the integration tests reset and use |
A Makefile wraps the common tasks with the pinned toolchain and a hermetic
(offline, vendored) environment. Run make to list targets:
make build # build bin/server (embeds whatever is in web/dist)
make release # build the front end into web/dist, then the server
make run # build and run the server
make test # full test suite from scratch (integration tests reset the DB)
make web-build # build only the front end into web/dist
make web-check # type-check + audit the front end
make vet # go vet
make fmt # gofmt -wmake build embeds the current contents of web/dist; use make release
(or run make web-build first) whenever the front end has changed.
Override connection strings on the command line, e.g.
make test TEST_DATABASE_URL=postgres://user:pass@host:5432/db?sslmode=disable.
The equivalent raw commands:
go build -o bin/server ./cmd/server
DATABASE_URL='postgres://tadmor:tadmor@127.0.0.1:5432/tadmor?sslmode=disable' go run ./cmd/server
TEST_DATABASE_URL='postgres://tadmor:tadmor@127.0.0.1:5432/tadmor_test?sslmode=disable' go test -count=1 ./...The server applies any pending migrations on startup. Endpoints: GET /healthz
(liveness), GET /readyz (database reachable).
The integration test drops and recreates the
publicschema ofTEST_DATABASE_URL. Point it only at a throwaway database.
Browser-driven UI tests (Playwright) live in e2e/, in their own project so the
test tooling stays out of the front end's runtime dependency tree. With the stack
running, make e2e-test drives a headless browser against the app. See
docs/e2e-testing.md for one-time setup, the supply-chain
rationale, and the test structure.
spec/ describes tadmor's API and business rules independently of
its technology stack, so the same product can be rebuilt on other stacks and
compared. make conformance runs the black-box suite in
conformance/ against a freshly built server on a wiped
tadmor_conformance database; see conformance/README.md.
The server is self-contained: the Go binary embeds the built SPA and the schema
migrations and serves the API, so the deployable artifact is a single static
binary (a container build also exists; see the repo-root Dockerfile). The demo
runs at https://tadmor.belunaro.com on a fixed-price VPS behind Caddy —
make deploy redeploys it; see docs/deployment.md for
the full setup. A guest account (guest@demo / guest123, non-admin) is open
for anyone who wants to poke around the demo — edit freely, the database is
reseeded nightly.
Deliberately minimal and standard-library-first to limit attack surface.
-
Standard library for HTTP, routing, JSON, logging, crypto.
-
Allowed third-party sources only:
github.com/jackc/pgx/v5(Postgres driver) andgolang.org/x/*. Anything else requires discussion first. -
Everything is vendored and pinned. All third-party source lives in
vendor/(committed, diffable in review); versions are locked ingo.sum. -
Builds are hermetic.
vendor/plus a pinnedtoolchainmean builds need no network. SetGOTOOLCHAIN=localto forbid toolchain auto-downloads andGOPROXY=offto forbid module fetches:go env -w GOTOOLCHAIN=local GOPROXY=off go build ./... # verifies the vendor tree is complete
Current compiled dependency tree (6 modules): pgx/v5, pgpassfile,
pgservicefile, puddle/v2, golang.org/x/sync, golang.org/x/text.