nucleus

Nucleus

Status: stable v1.x line. v1.0.0 was tagged 2026-07-10; the latest release is v1.28.0 and main tracks the next v1.x. The in-core admin panel was extracted to the separate orbit module (ADR-019). Public APIs are classified stable, transitional, or experimental (see docs/reference/API_CONTRACT_INVENTORY.md) and frozen by an automated contract test. The Compatibility SLO is active: application code on stable surfaces will not need rewrites within v1.x.

Nucleus is a web framework for Go. It pairs the ergonomics of a Django-style CLI with a stdlib-first runtime: net/http, database/sql, and log/slog are the substrate; everything else is added intentionally and stays behind framework-owned adapter boundaries so it can be swapped without breaking application code.

The framework ships as a core Go module plus twelve optional modules — the five database drivers (drivers/postgres, mysql, sqlite, mssql, oracle), the two telemetry exporters (exporters/otlp, prometheus), the three cloud storage providers (providers/storage-s3, storage-gcs, storage-azure), the AWS secrets resolver (providers/secrets-aws) and the LDAP backend (providers/ldap) — and a single CLI binary (nucleus). An application links only what it uses, with a blank import that nucleus add <name> writes for you (ADR-030, ADR-031). The admin panel is not in the core either — it ships as the separate orbit module, mounted in-process when an app wants it (ADR-019). Nucleus targets long-lived systems, not one-shot prototypes.

Why Nucleus

• stdlib-first runtime. net/http, database/sql, log/slog, context are used directly — no Gin/Chi/Echo, no GORM/Bun/Ent, no zap/zerolog, no per-framework debugger plumbing in stack traces. (ADR-001)
• Django-inspired CLI, Go-native semantics. 40 lifecycle commands — nucleus serve, migrate, createuser, inspectdb, dumpdata, loaddata, mailproviders, plugin doctor, makemessages, compilemessages, collectstatic, etc. — with both Go-style names and Django-compatible aliases (runserver, makemigrations, createsuperuser, dbshell). (ADR-002)
• The pieces you are most likely to replace are pluggable. Storage backends, session stores and authentication backends are selected by name from a registry, so running Ceph instead of S3 — or authenticating against a corporate directory — does not mean forking the framework. A provider brings its own configuration subtree, and the built-ins register through the same public call as anyone else. (ADR-023)
• Authentication as an ordered chain. auth_backends: [ldap, local] consults the directory first and falls through to your own user table when the directory cannot be reached — which is what makes a break-glass account work the morning it is needed. A backend that rejects ends the attempt; one that is unreachable is skipped, and the caller can tell the two apart.
• Out-of-process plugins too. The plugin SDK v1 uses capability envelopes (mail.send, queue.publish, webhook.deliver) discovered via the nucleus-plugin-<provider> PATH convention, for backends that should not share the application's process.
• Admin via orbit. The admin panel — auto-generated CRUD against registered models, a live request/SQL feed (single binary or multi-node via Redis), RBAC management, audit log, and operational views — ships as the separate orbit module, mounted in-process. The core exposes the Runtime accessors orbit reads (model registry, DB handles, session manager, RBAC enforcer, observability bus); it no longer bundles a UI.
• Multi-database, multi-engine. SQLite, PostgreSQL, MySQL are required lanes; MSSQL and Oracle run as live lanes too, with parity tests for migrations, fixtures, sessions, cache, and inspect commands. Each driver is its own module (nucleus add postgres|mysql|sqlite|sqlserver|oracle), so an application carries one engine, not five — and the module also registers the error classifier that turns a duplicate key into a 409.
• Operational depth. Transactional outbox with leasing dispatcher, task scheduler with periodic and queue-runtime helpers (Asynq + Redis), signals bus with optional Redis relay, OpenTelemetry tracing/metrics, structured logging with request correlation, deploy-readiness health command, and doctor checks for plugins/tasks/storage/observability.
• Multi-tenant and multi-site. Subdomain or header-based tenant resolution, per-tenant DB isolation, automatic storage prefixing, a rate limiter keyed by user and tenant once the request is authenticated (by client IP before that; by route with rate_limit_by_route, by role with rate_limit_by_role), and explicit override APIs when you need to step around the convention.

5-minute start

go install github.com/jcsvwinston/nucleus/cmd/nucleus@latest

nucleus new myapp --module github.com/acme/myapp
cd myapp
nucleus generate module notes --mount
go run .

nucleus new generates a minimal skeleton — a composition-root main.go, nucleus.yml, .gitignore, and an empty migrations/ directory — with the database driver already resolved (--db picks the engine, --offline skips the network). There is no pre-built demo content: generate module --mount writes your first feature as a self-contained package (routes, storage, policy rows, embedded migrations, a test) and mounts it in main.go. The mvc template runs with full framework defaults and includes rbac_policy.csv (the default-deny Casbin policy); to add an admin UI, mount the orbit module. The api template uses WithoutDefaults() and serves only /healthz.

Open after go run .:

To build your first feature module, see the working reference application in examples/mvc_api — it adds a notes REST resource on the fluent nucleus.Module surface and is the canonical starting point.

Generated projects are self-contained: go.mod already requires the right Nucleus version, no replace directive, no Nucleus source tree needed.

Minimal API in code

package main

import "github.com/jcsvwinston/nucleus/pkg/nucleus"

func main() {
    nucleus.New().
        FromConfigFile("nucleus.yml").
        WithoutDefaults().
        Start()
}

Add features as modules; see examples/mvc_api for a complete worked example using the nucleus.Module surface. The fluent package is a façade over the same pkg/app runtime.

What's in the box

Runtime packages

See docs/reference/API_CONTRACT_INVENTORY.md for the contract per package.

CLI command groups

Project lifecycle    new, startapp, wizard, generate, add, serve, health, doctor
Database             migrate, sqlmigrate, sqlflush, sqlsequencereset,
                     squashmigrations, optimizemigration, inspectdb,
                     ogrinspect, shell, flush
Data                 loaddata, dumpdata, seed, outbox
Cache & sessions     createcachetable, clearsessions,
                     remove_stale_contenttypes
Identity             createuser, changepassword
Mail                 mailproviders, sendtestemail
Plugins              plugin list, plugin doctor, plugin test
Static & i18n        collectstatic, findstatic, makemessages,
                     compilemessages
Contracts            openapi
Diagnostics          config, diffsettings, routes, testserver, test

Aliases mirror Django where it is unambiguous: runserver, startproject, makemigrations, showmigrations, createsuperuser, dbshell. The global output flags --json, --output, --color, --symbols are honoured by the inspection commands (health, routes, config, mailproviders, plugin, cache/contenttype/static tooling); adoption across the remaining commands is tracked, not claimed.

Configuration

A single nucleus.yml per project (extension is .yml, not .yaml). All keys are versioned in docs/reference/CONFIG_KEY_REGISTRY.md and frozen by contracts/baseline/config_key_patterns.txt.

Credentials never live in plaintext in source. Every sensitive value accepts the CredentialSource shape (value / env_var / file / secret_manager) for K8s secrets, mounted volumes, or cloud secret managers.

Reference applications

Two reference applications ship in-tree:

• examples/mvc_api — the canonical worked module: a notes REST resource on the fluent nucleus.Module surface (package-per-feature, mounted with one line). Reintroduced against the ADR-010 API after the original examples/* tree was removed in Phase 1 (2026-05-16) so it would not constrain the fluent surface during its rewrite.
• examples/showcase_demo — the three suite products working together (Nucleus app + Quark ORM + orbit panel), with the integration bridges wired and curls included. It is its own Go module so Quark and orbit stay out of the framework's dependency graph.

nucleus generate module <name> scaffolds a new feature in the same package-per-feature shape: one package under internal/<name>/ whose module carries its routes, storage, policy rows, CSRF exemption, embedded migrations and page template — mounting it is the whole integration (see ADR-022).

Documentation map

The user-facing documentation is the public site: jcsvwinston.github.io/quantum/nucleus (source: website/docs/). It is the living narrative — quickstart, concepts, features, operations, reference — and wins over the internal guides below when they disagree. What follows is the in-repo map: contracts, governance and the internal depth the site links into.

Start here

• docs/QUICKSTART.md — 5-minute walkthrough, more detail than this README
• docs/guides/DETAILED_TUTORIAL.md — End-to-end tutorial app
• docs/reference/PROJECT_LAYOUT.md — Generated project conventions

Build

• docs/guides/MODELING_MULTI_DATABASE.md
• docs/guides/AUTH_GUIDE.md · CSRF_GUIDE · VALIDATION_GUIDE · ERROR_HANDLING
• docs/guides/STORAGE_GUIDE.md · SIGNALS_GUIDE
• docs/guides/MULTISITE_GUIDE.md · RATE_LIMITING_GUIDE
• Admin panel: see the orbit module (extracted from the core, ADR-019)
• docs/reference/PLUGIN_SDK.md — the capability contract (no runnable example plugin ships in-tree today)

Operate

• docs/guides/DEPLOYMENT_GUIDE.md
• docs/guides/OBSERVABILITY_BASELINE.md
• docs/guides/TESTING_GUIDE.md
• docs/reference/CLI_BEST_PRACTICES.md · CLI_CONTRACT_MATRIX

Govern

• SPEC.md — Single canonical spec (runtime, deps, config, CLI, governance)
• docs/governance/COMPATIBILITY_SLO.md · RELEASE_CHECKLIST · CI_MATRIX
• docs/governance/DEPRECATION_TEMPLATE.md · MIGRATION_ASSISTANT_CONVENTIONS
• docs/governance/ENTERPRISE_LONG_TERM_ROADMAP.md — Tracks A → G
• docs/adrs/ — Architecture Decision Records, from 001 (stdlib-first) to 031 (drivers and exporters as modules)

Compatibility and contracts

Six text files in contracts/baseline/ freeze the public surface and are checked on every CI run:

The first four block removals: new surface area is allowed and captured in the next baseline commit.

The last two block change in both directions, for the same reason. An extension-facing field appearing is a promise to plugin authors, so it is made on purpose rather than by accident. And a security default that gets stricter changes the behaviour of deployments that relied on the old one, which is a compatibility event even though it sounds like an improvement.

The security posture baseline is also the only one that is measured rather than transcribed: it comes out of a real HTTP response from a really booted application, so it cannot claim a protection the framework does not emit. See contracts/freeze_test.go, contracts/firewall_test.go, contracts/extension_surface_test.go and contracts/security_posture_test.go.

Requirements

• Go 1.26+ (the exact minimum is the go directive in go.mod — the only place that number lives)
• One database driver module: drivers/sqlite, drivers/postgres, drivers/mysql (required lanes), drivers/mssql or drivers/oracle (live lanes) — nucleus add <engine> adds the import
• Optional: Redis (sessions, tasks, signals relay; orbit's multi-node live cluster)

For local dev, docker-compose.yml brings up Postgres, MySQL, MariaDB, Redis, SQL Server, Oracle and Jaeger instances aligned with the test matrix.

License

Apache-2.0 — see LICENSE.