Nucleus

Why Nucleus

Production-grade, Go-idiomatic, no surprises.

Six properties define the framework. Each is enforced by tests, not by aspirations in a README.

Stdlib-first runtime

Built on net/http, database/sql, log/slog and context. New third-party deps require an ADR and a dependency-impact review.

Compatibility by contract

Public symbols in pkg/*, registered CLI commands and config keys are pinned by freeze tests under contracts/. No silent removals.

Embedded admin panel

React + TypeScript admin auto-generated from your registered models. CRUD, bulk actions, audit log, RBAC, multi-tenant filters — all in the binary.

SQL-first data layer

Plain database/sql with health checks, telemetry, and SQL migrations. No ORM. Postgres, MySQL, SQLite by default; MSSQL and Oracle as build tags.

Secure by default

Argon2id passwords, CSRF on for state-changing form posts, secure cookies in production, CORS that denies unknown origins, rate limiting on every public route.

Observability built in

Structured slog logging, OpenTelemetry traces and metrics, deterministic /healthz endpoints. Configure once in nucleus.yml.

Fluent or full-MVC

One construction call. Everything wired.

The fluent entry point assembles a full application — config, database, model registry, router, handlers — in a builder you can read top-to-bottom. For real projects, the same wiring lives in cmd/server/main.go.

No init-time side effects. No hidden globals.
Multiple App instances per process for tests.
Lifecycle observable: Run, Shutdown, hooks.
Same primitives the scaffold templates emit.

package main

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

type Article struct {
    ID    int64   `json:"id"    db:"id,primary"`
    Title string  `json:"title" db:"title" validate:"required"`
}

func main() {
    nucleus.New().
        Port(8080).
        SQLite("app.db").
        Model(&Article{}).
        AutoMigrate().
        Get("/api/articles", listArticles).
        Run()
}

What's in the box

Subsystems, all governed by the same contract.

Each subsystem ships with sane defaults, structured logging, health hooks and a place in the embedded admin.

Applicationpkg/app

Composition root. Lifecycle, extensions, request scope.

Routerpkg/router

HTTP router + middleware: CORS, CSRF, rate limit, OTel.

Databasepkg/db

database/sql wrapper with telemetry, health, migrations.

Modelspkg/model

Metadata-driven registry. Drives admin and CRUD.

Authpkg/auth

JWT, Argon2id, session manager (memory/SQL/Redis).

Adminpkg/admin

Embedded React admin generated from your models.

Storagepkg/storage

Local, S3, GCS, Azure — one provider-agnostic API.

Taskspkg/tasks

Background jobs on Asynq + Redis with outbox.

Ship a real app this afternoon.

Install the CLI, scaffold a project, and have a database, an admin panel, and a REST API running locally before the kettle boils.

Install the CLI →Read the principles