A reusable SaaS foundation for Go and React.
New SaaS projects pull in the capabilities they need via go get / npm install, generate a minimal starter skeleton with a CLI, and start with multi-tenant isolation, authentication and permissions, organizations and members, subscription billing and metering, an AI gateway, background jobs, media storage, notifications, observability and an operations console already in place.
Implementation has moved well past the framework's original M0 milestone. Of the modules the roadmap spreads across M0 through M4, all but M4's deepest compliance-governance work are landed on main with tests passing — several of them (storage, notification, ai-gateway, integration, admin, compliance) shipped well ahead of the milestone window they were originally scheduled for, plus one module, pki (signing-key and X.509 lifecycle management), that wasn't on the original roadmap at all. Naming the status by milestone number is no longer the useful framing here; naming what's real is: 21 Go modules have real, tested implementations today — go build, go vet, golangci-lint run ./... and go test -race all pass for every one of them, and CI proves it on every pull request. That's the infrastructure floor (pkgcore, dbkit, tenancy, observability, config, jobs, ratelimit, pki), identity and access (authn, rbac, org), media and monetization (storage, notification, billing, metering), growth and integration (sharing, integration, ai-gateway), governance (compliance, admin), and the consumer-facing scaffolding CLI (saasctl) — every module the root go.work file lists, with none left as an unimplemented stub. On the web side, eleven @speed/* npm packages — tokens, i18n, ui-kit, api-client, api-sdk, layout-kit, auth-core, auth-ui, tenancy-ui, product-shell and account-ui — are implemented, tested, and lint/typecheck/build clean under the web/ pnpm workspace, alongside the reference app's own web host (examples/reference-app/web), which rides that same workspace as an unversioned twelfth member and proves the whole frontend stack composed together.
Six OpenAPI fragments (notes, org, authn, storage, notification, sharing) already drive the spec-first loop end to end today, and CI enforces it across six live pipelines. fast-check runs on every pull request and on every push to main — most commits land on main by a direct push rather than a merged pull request, so the push trigger is the normal path, not a fallback for an edge case: lint, vet and race-tested unit tests for all 21 Go modules, the matching lint/typecheck/test/build pass for all eleven npm packages plus the reference app's web host, and repository-wide checks (a CJK-outside-docs/internal-scan, a workspace-wide build, a go.work drift gate). full-check adds the Docker-backed PostgreSQL/Redis/MinIO integration tiers and the reference app's own composed-HTTP flow tests, gated behind a full-ci label on pull requests — but, like fast-check, it also runs on every push to main, since that's where most commits actually land. docs-check runs the i18n key-parity check on PRs touching documentation or i18n resources. api-contract regenerates the backend interface for all six spec fragments — and, for the three that feed the merged document (notes, authn, notification), the @speed/api-sdk frontend too — and rebuilds the reference app, so a spec change nobody implemented cannot compile. Two more fragments, admin and pki, exist but aren't wired into this pipeline yet. security runs a dependency audit, a secret scan, CodeQL and a license check on every PR plus a daily schedule. release is dispatched manually and verifies a lockstep, one-version release plan entirely offline; no publish credential is wired yet, so real publishing stays a v1.0 milestone. Three further workflow files (e2e, nightly, scaffold-verify) exist but are deliberately gated stubs until their own implementation rounds land.
What's still ahead, in short: nothing has ever booted in the distributed deployment mode itself (every module is proven standalone, with the distributed-mode infrastructure exercised only in a standalone topology); owner-facing share-link management ships service-level only, with no HTTP surface yet — PKI's X.509/CA layer, by contrast, already has its own HTTP surface (revocation, CRL, JWKS export), just no real consumer yet and no api-contract.yml regenerate-and-diff gate; compliance has already landed retention-window cleanup, immediate right-to-erasure with cross-tenant non-erasure proven, and export delivery through sharing as a short-lived link — what's genuinely still deferred there is narrower: immutable database-level enforcement, an optional hash chain, formatted report export, and partitioned archival, alongside admin's still-pending role management, usage dashboard and per-tenant enforcement round; and the browser-page/end-to-end test legs and the v1.0 release itself are still ahead.
- 📐 Design overview ← start here
- 🗺️ Roadmap and milestones
⚠️ Risk register
Design documents under
docs/internal/are written in Chinese for internal design discussion. Everything else in this repository — code comments, module docs, public documentation — is English.
| Choice | What it means |
|---|---|
| Import modules, don't fork | Capabilities ship as independently released Go modules and npm packages; only the minimal starter skeleton is generated by a CLI and freely editable |
| Modular monolith | Modules are released independently but compiled into a single binary and called in-process — no service mesh, no Kubernetes-shaped infrastructure |
| Two deployment modes | The standalone deployment mode runs as a single process with zero external dependencies and starts in seconds; the distributed deployment mode adds PostgreSQL, Redis and the observability stack |
| Lockstep versioning | Every module shares one version number; only same-version combinations are supported, so there is no compatibility matrix |
| Contract first | Every REST API has OpenAPI as its single source of truth, and all frontend call code is generated — front/back drift is caught by the compiler |
| Bilingual by default | Chinese and English from day one, never retrofitted |
| Validated against real requirements | A built-in reference-app is the mandatory first consumer of every module |
speed/
go/ 21 Go modules (pkgcore / tenancy / authn / rbac / billing / jobs / ...)
web/ 11 npm packages (ui-kit / auth-core / api-sdk / layout-kit / ...), a pnpm workspace
examples/ reference-app: the AI smile simulation platform, backend and its own web host
build/ generated artifacts (the merged OpenAPI document)
tools/ repo-wide tooling: the release coordinator, CI lint and drift-check scripts
docs/
internal/ design documents (Chinese)
adr/ architecture decision records
site/ public documentation for consuming teams
A consumer project's starter skeleton comes from go/saasctl's own embedded template tree (saasctl new), not a separate top-level directory; layered docker-compose files for local distributed-mode development are still planned but not yet shipped. The full layout and release strategy live in 02 Repository and Release.
| Standard | Applies to |
|---|---|
| Backend coding standards | all Go code under go/** |
| Frontend coding standards | all React/TypeScript code under web/** |
| Commit convention | every git commit |
In Claude Code these three load automatically as skills; otherwise read the files directly.
Read CLAUDE.md first — it carries the architecture overview, the full discipline list, and pointers to everything else. Then follow the three standards above when writing code.