keelstack

README

Keel

Keel is a Go application platform for modular monoliths and production-grade services.

It is designed for teams that want consistent production behavior without turning application code into framework-driven magic.

It standardizes the backend plumbing every serious service needs:

• typed configuration
• structured logging
• canonical error handling
• HTTP transport and middleware
• production auth primitives
• database access
• observability
• storage, mail, queue, and search adapters
• scaffold, templates, and test helpers

Keel is not a business framework.

It does not own your domain model, CRUD flows, repository hierarchy, or query DSL. It gives teams a stable, explicit, reviewable platform baseline so product code stays readable and operations stay consistent.

Who Keel Is For

Keel is a strong fit for teams that want:

• a Go backend platform with explicit code paths
• modular monoliths as the default delivery model
• production-safe defaults for auth, errors, observability, and integrations
• scaffold, templates, and reference implementations instead of tribal knowledge
• reusable plumbing without leaking business rules into the platform

Keel is a poor fit if you want:

• a low-code CRUD generator
• framework-owned domain workflows
• annotation-heavy runtime behavior
• a platform that hides architectural decisions from the service code

What A Team Should Be Able To Do With Keel

Using the repo and docs alone, a new team should be able to:

• run a real reference service locally
• understand where auth, policy, DB, and outbox logic live
• scaffold a new in-repo service safely
• adopt CI/CD templates with clear merge gates
• troubleshoot startup, dependency, and runtime failures
• review platform behavior with explicit security and compatibility contracts

What Keel Is

• Modular monolith first
• Pragmatic DDD when domain complexity justifies it
• Explicit flows over framework magic
• Platform for plumbing, not for business rules
• Production readiness by default

What Keel Deliberately Avoids

Keel should not become:

• a second framework layered on top of Go
• a generic CRUD engine
• a universal ORM abstraction
• a workflow runtime
• a hidden authorization engine
• a reflection-heavy codebase that is hard to debug or review

Read This First

Start here if you want the full architectural picture:

• Implementation Contract
• Application Platform Design
• Reference Architecture
• Security Baseline
• Engineering Standards
• Enablement Contract
• Review Checklist
• Roadmap
• Platform Maturity
• Membership and RBAC Model

If you only read three things:

1. Quickstart
2. Cookbook Index
3. Implementation Contract

Architecture At A Glance

Keel expects application code to stay explicit:

transport -> app -> domain -> infra
             |
             -> policy

• platform/* provides shared infrastructure and cross-cutting concerns
• cmd/*/internal/* owns domain behavior
• policy stays visible in project code
• authn lives in middleware, authz lives in application/policy code
• transactions are application-owned, not hidden inside a repository framework

Prerequisites

To use the repository as documented:

• Go 1.25+
• Docker and Docker Compose
• PostgreSQL via docker compose
• OpenSearch via docker compose when you want search-backed examples

Fastest Way To Get Running

If you want a live service first and architecture second:

cp .env.example .env
docker compose up -d postgres

REF_ENV=development \
REF_AUTH_SECRET=dev-secret-min-32-chars-padding12 \
REF_DB_URL=postgres://keelstack:changeme-local-only@localhost:5432/keelstack?sslmode=disable \
go run ./cmd/reference-monolith

Then:

curl -s http://localhost:8090/healthz
curl -s http://localhost:8090/readyz

Full onboarding guide:

• Quickstart

What this proves:

• your local environment can run a Keel service
• DB-backed readiness checks are working
• the reference monolith boot path is healthy
• you have a baseline for exploring auth, reports, audit, and access flows

Which Example To Start With

Path	Use it when	What it proves
cmd/example-app	You want the smallest possible vertical slice	Foundation packages wired together end-to-end
cmd/integration-example	You want adapter examples	Storage, mail, queue, and search integrations
cmd/reference-monolith	You want the full reference service	Auth, DB, access control, audit, report flow, outbox, search
cmd/scaffold	You want to generate a new in-repo service/module/migration/ADR	Repeatable bootstrap path for Keel-based development
template/service	You want to inspect the baseline service shape directly	Explicit bootstrap and package wiring
template/cicd	You want CI/CD baselines	Lint, test, vuln-scan, container-scan, release, deploy templates

Recommended Adoption Paths

Path A — evaluate the platform quickly

1. Run Quickstart
2. Inspect cmd/example-app
3. Read Platform Package Cookbook

Path B — understand a real service shape

1. Run cmd/reference-monolith
2. Read Reference Monolith Walkthrough
3. Read Membership and RBAC Model
4. Review Security and Operations Cookbook

Path C — bootstrap your own service inside the repo

1. Read Scaffold Guide
2. Run go run ./cmd/scaffold service ...
3. Compare generated code with template/service
4. Adopt template/cicd

Copy-Paste Documentation Map

For teams who want runnable commands and concrete examples:

• Quickstart: local environment, first run, first request
• Cookbook Index: all example-driven docs from one page
• Platform Package Cookbook: when to use each package and how
• Reference Monolith Walkthrough: request path and startup sequence
• Scaffold Guide: generated service/module/migration/ADR flow
• CI/CD Guide: template adoption and branch protection
• Security and Operations Cookbook: safe production defaults and common mistakes
• Troubleshooting and FAQ: failure modes and fixes

For architecture, governance, and package contracts:

• Execution Plan
• Backlog Plan
• Package Specs
• ADRs
• Rollout and Migration Guide
• Adoption Feedback
• Phase 4 Exit Evidence

Production-Safe Defaults

Keel treats these as non-negotiable defaults unless an ADR says otherwise:

• auth verification must fail closed
• 5xx error detail must not leak internals
• logs must redact sensitive fields centrally
• external clients must enforce TLS correctly
• DB readiness must block traffic when dependencies are unavailable
• CI must treat lint, test, and security checks as real gates
• platform changes that alter compatibility or security posture require explicit documentation

Repository Map

Path	Purpose
platform/	Reusable platform packages
cmd/example-app	Minimal reference app
cmd/integration-example	Adapter/integration reference app
cmd/reference-monolith	Full modular monolith reference
cmd/scaffold	Scaffold CLI
template/service	Service baseline template
template/cicd	CI/CD workflow templates
docs/	Architecture, specs, cookbook, governance, security

Platform Surface

Foundation

• platform/config - typed environment-driven configuration
• platform/log - structured logging with central redaction
• platform/errors - canonical error codes with RFC 7807 mapping
• platform/httpx - HTTP server helpers, middleware chain, JSON helpers, health probes
• platform/auth - principal model, auth middleware, OIDC/JWKS verification
• platform/db - PostgreSQL pool, health checks, transaction helpers
• platform/obs - tracing, metrics, request and trace correlation

Adapters

• platform/storage - object storage with validation hooks
• platform/mail - transactional mail contract and adapters
• platform/queue - envelope, publisher, consumer, outbox helpers
• platform/search - full-text search client boundary
• platform/testkit - fake auth, test helpers, HMAC verifier for tests only

Enablement

• cmd/scaffold - service, module, migration, ADR generation
• template/service - baseline service structure
• template/cicd - reusable GitHub Actions workflows
• cmd/reference-monolith - enterprise-grade integration reference

Important Adoption Notes

Scaffold is for in-repo service generation

scaffold service currently generates services inside the Keel repository/module. That is intentional and documented in:

• Quickstart
• Scaffold Guide

Generated services import github.com/VenoMexx/keelstack/platform/... and are expected to build inside the same module unless your team sets up a separate private-module consumption strategy.

That is a deliberate choice: today Keel is optimized for controlled in-repo adoption, not anonymous public package consumption.

Membership and RBAC are not platform-owned

Keel provides auth primitives. Tenant membership, role bindings, resource-level authorization, and policy decisions stay in project code. The reference access model lives here:

• Membership and RBAC Model

Security behavior must remain fail-closed

Before relaxing any default, read:

• Security Baseline
• Threat Model
• Dependency Audit

Enterprise Readiness Signals

The repository already contains the artifacts an enterprise team typically asks for:

• package-level specs under docs/specs
• explicit ADR history under docs/adr
• security baseline, threat model, and audit notes under docs/security
• CI/CD workflow templates under template/cicd
• a reference service with auth, DB, outbox, audit, search, and access control
• rollout and migration guidance under docs/rollout-migration-guide.md

Status

Phase	Status	Notes
Phase 1 - Foundation	Complete	Core platform packages implemented and tested
Phase 2 - Adapters	Complete	Storage, mail, queue, search, testkit available
Phase 3 - Enablement	Complete	Scaffold, templates, cookbook, reference monolith available
Phase 4 - Hardening	In progress	Repo-level hardening is strong; external adoption evidence is still being accumulated

Detailed status:

• Roadmap
• Platform Maturity
• Phase 4 Exit Evidence

Why This Repository Exists

Keel exists to make backend teams faster without hiding the code they have to maintain.

The platform standardizes:

• configuration and bootstrap
• transport and error contracts
• security defaults
• observability
• database and integration boundaries
• templates and delivery workflow

It does not standardize:

• product use cases
• domain model behavior
• business permissions
• domain event choreography

Contributing

Before changing platform behavior:

1. Read Contributing
2. Check Engineering Standards
3. Check the relevant package spec under docs/specs
4. Write or update an ADR if the change affects architecture, compatibility, or security posture

License

See the repository license file when published for external reuse.