# SummerCMS

> SummerCMS is a content management framework for Go, inspired by WinterCMS.

- Plugins are Go modules compiled into the application binary and registered at build time; nothing is loaded at runtime.
- The data layer supports PostgreSQL only.
- SummerCMS is headless: it serves a JSON API and an admin SPA, with no frontend themes.
- It targets Go 1.27.

## Overview

- [SummerCMS documentation](/docs/index.md): SummerCMS is a content management framework for Go, inspired by WinterCMS.

## Setup

- [Introduction](/docs/setup/introduction.md): What SummerCMS is, who it is for, how its headless model works and how this documentation is organised.
- [Installation](/docs/setup/installation.md): Install the Go toolchain, PostgreSQL and the summer CLI, then build, configure, migrate and serve your first SummerCMS application.
- [Configuration](/docs/setup/configuration.md): Configure an application with YAML files, per-environment directories, plugin defaults and SUMMER_ environment variables, and set the keys it needs.
- [Coming from WinterCMS](/docs/setup/coming-from-wintercms.md): Map WinterCMS plugins, models, backend controllers, routes, events and commands to their SummerCMS equivalents, and see what is not provided.
- [Porting a plugin](/docs/setup/porting-a-plugin.md): Take a WinterCMS acme/blog plugin with a model, migrations, a route, a backend controller and an artisan command to a compiled SummerCMS plugin, step by step.

## Architecture

- [Architecture introduction](/docs/architecture/introduction.md): How a SummerCMS application is built: one Go binary with compiled plugins, a headless JSON API, an embedded admin SPA and console commands.
- [Go modules and workspaces](/docs/architecture/go-modules-and-workspaces.md): Require the framework module, develop plugins as local modules in a Go workspace, list them in summer.yaml and fork a plugin with a replace directive.
- [Application lifecycle](/docs/architecture/application-lifecycle.md): What happens when an application binary starts: configuration, the backpack container, plugin ordering, Register and Boot, and database-dependent boot work.
- [Request lifecycle](/docs/architecture/request-lifecycle.md): How an HTTP request reaches a plugin handler: route collection, named middleware, constraints, body limits, CORS, recovery and request context values.
- [Performance and scaling](/docs/architecture/performance-and-scaling.md): Why a SummerCMS binary serves requests faster and with less memory than WinterCMS on PHP-FPM, where it does not, and how to scale and measure it.

## Plugins

- [Plugin registration](/docs/plugins/registration.md): Declare a plugin: its ID, the party.Plugin lifecycle, the pact capability interfaces it opts into, its embedded files and the scaffolded layout.
- [Task scheduling](/docs/plugins/scheduling.md): Run a plugin's console commands on a schedule with pact.HasSchedule, and run the scheduler in the worker, as its own process or from system cron.
- [Extending plugins](/docs/plugins/extending.md): Extend other plugins through typed events, published services, optional dependencies and GORM callbacks, and replace a plugin by forking its module.
- [Testing plugins](/docs/plugins/testing.md): Test plugins with go test, run database tests against real PostgreSQL containers, replay API parity fixtures and keep documentation examples running.

## Backend

- [Admin controllers](/docs/backend/admin-controllers.md): Declare admin controllers with pact.AdminController and WinterCMS-shaped YAML, and let the generic JSON admin API list, show, create, update and delete records.
- [Forms](/docs/backend/forms.md): Describe admin forms in config_form.yaml and fields.yaml, with the supported field types, spans, tabs, dropdown options and create or update contexts.
- [Lists and filters](/docs/backend/lists-and-filters.md): Describe admin lists in config_list.yaml and columns.yaml, with search, sorting, pagination options and switch, date range and scope filters.
- [Relation manager](/docs/backend/relation-manager.md): Edit belongsTo and belongsToMany relations in admin forms and manage linked records with config_relation.yaml, bound to models the controller names.
- [Users and permissions](/docs/backend/users-and-permissions.md): Sign administrators in with JWT and cookie auth, declare permissions and navigation, and manage administrators from the console.
- [Settings](/docs/backend/settings.md): Declare singleton settings pages with pact.SettingsItem, backed by a model, a fields.yaml form and validation rules, and read them from plugin code.
- [Partials and widgets](/docs/backend/partials-and-widgets.md): Extend admin screens with server-rendered partials, plugin JavaScript and CSS, form widgets backed by server actions, and custom toolbar buttons.
- [Admin SPA](/docs/backend/admin-spa.md): How boardwalk serves the embedded Vue admin SPA under backend.uri, how the SPA talks to the admin API, and how its TypeScript types come from OpenAPI.

## Database

- [Models](/docs/database/models.md): Define models as GORM structs with lagoon helpers for mass assignment, hidden columns and lifecycle hooks, and keep the models package a leaf.
- [Migrations](/docs/database/migrations.md): Ship a plugin's schema as an ordered gormigrate set through pact.HasMigrations, and run, inspect and roll back migrations per plugin.
- [Queries and pagination](/docs/database/queries-and-pagination.md): Query models with GORM, sort by a client-chosen column safely with lagoon.OrderBy, and return Laravel-shaped pages with lagoon.Paginate.
- [Relations](/docs/database/relations.md): Declare relations as GORM associations, write pivot tables with business columns explicitly, and cascade soft deletes inside the parent delete.
- [Casts and validation](/docs/database/casts-and-validation.md): Store JSON and encrypted columns with lagoon.Jsonable and lagoon.Encrypted, and validate input with Laravel-style rule strings through lagoon.Validate.
- [Attachments](/docs/database/attachments.md): Attach files to models through WinterCMS-compatible system_files rows, serve originals and thumbnails, and delete blobs only after the transaction commits.
- [Transactions](/docs/database/transactions.md): Run writes in lagoon.Transaction, defer side effects with lagoon.AfterCommit until the commit, and install GORM callbacks from Boot with lagoon.OnDatabase.

## Services

- [Configuration](/docs/services/configuration.md): Read layered configuration with compass, from plugin defaults through per-environment files and SUMMER_ variables to runtime overrides saved to disk.
- [Events](/docs/services/events.md): Listen for and fire typed events on the application bus with festival, with priorities, collected results and a halting fire that stops when handled.
- [Routing](/docs/services/routing.md): Declare a plugin's HTTP routes with groups, auth groups, path constraints and named middleware through pact.HasRoutes, and write JSON responses with wire.
- [Rate limiting](/docs/services/rate-limiting.md): Throttle routes with inline limits or named buckets, key them by user or client IP, and trust X-Forwarded-For only from configured proxies.
- [Authentication](/docs/services/authentication.md): Mint and verify JWTs with bouncer, turn guards into route middleware, revoke tokens through a jti blacklist and hash passwords with bcrypt.
- [OAuth server](/docs/services/oauth-server.md): Let MCP clients act for your users with the wristband OAuth server, covering metadata, dynamic client registration, PKCE, consent and refresh token rotation.
- [Mail](/docs/services/mail.md): Ship WinterCMS-style mail templates in a plugin, send them through postcard, and deliver them with the memory, log or SMTP driver.
- [Localization](/docs/services/localization.md): Ship plugin translations in lang YAML catalogs, translate with :name placeholders and CLDR plurals through phrasebook, and read the request locale.
- [Storage](/docs/services/storage.md): Configure the uploads bucket that serve opens, choose file or memory bucket URLs, serve stored files, and size upload routes.
- [Outbound HTTP](/docs/services/outbound-http.md): Fetch URLs that users or third parties supply through fetchguard, which allows HTTPS only, blocks private addresses at dial time and limits size and time.
- [Queued jobs](/docs/services/jobs.md): Declare background jobs with conga.Job, dispatch them inside the caller's transaction, track them in summer_jobs and run workers in serve or on their own.
- [Realtime](/docs/services/realtime.md): Publish model changes and events to realtime channels with lighthouse, authorize subscriptions per channel namespace, and run the Centrifugo driver.
- [Web Push](/docs/services/push.md): Send browser push notifications with flare over VAPID, only to https push service hosts on push.allowed_hosts and without redirects, and manage VAPID keys.
- [Search](/docs/services/search.md): Keep models in a search index with beachcomber, synced after commit behind a kill-switch, and re-check the candidate IDs a search returns in SQL.
- [Parity testing](/docs/services/parity-testing.md): Record the reference backend's responses and broadcasts with tide, replay them against the Go port and diff them after masking IDs and timestamps.
- [Frontend and AJAX (not provided)](/docs/services/frontend-and-ajax.md): SummerCMS is headless, so CMS pages, themes, components, the AJAX framework and Snowboard are not provided; build the frontend as a separate application.

## Console

- [Console introduction](/docs/console/introduction.md): The two command-line programs of SummerCMS, the summer developer tool and the application binary, and how summer delegates runtime commands.
- [Setup and maintenance](/docs/console/setup-and-maintenance.md): Every runtime command of an application binary, with its flags and purpose, from migrations and the server to workers, admin accounts and realtime checks.
- [Scaffolding](/docs/console/scaffolding.md): Build and watch an application, and generate plugins, models, migrations, console commands, jobs and admin controllers with the summer make commands.
- [Writing commands](/docs/console/writing-commands.md): Add console commands to a plugin with bonfire.Command values, arguments, flags, styled output and prompts, and run commands in-process.
- [Utilities](/docs/console/utilities.md): The summer commands for API parity testing and for building, syncing and previewing this documentation, with their flags.

## API reference

- [backpack](/docs/api/backpack.md): Per-instance application container that holds the configuration, a typed service registry, the event bus and the set of activated plugins.
- [beachcomber](/docs/api/beachcomber.md): Search index sync for GORM models: after-commit upserts and deletes through a pluggable engine, gated by an application kill-switch.
- [boardwalk](/docs/api/boardwalk.md): HTTP handler that serves the embedded admin SPA build under a configurable path prefix.
- [bonfire](/docs/api/bonfire.md): Declarative console commands for the `summer` tool and application binaries, adapted to Cobra with typed input, prompts and styled output.
- [bouncer](/docs/api/bouncer.md): Authentication for SummerCMS: HS256 JWT minting, verification and refresh, request guards, a revoked-token blacklist and bcrypt password helpers.
- [cabana](/docs/api/cabana.md): Schema-driven admin backend that compiles WinterCMS-style YAML list, form, filter and relation definitions at boot and serves them as a JSON admin API next to the embedded admin SPA.
- [compass](/docs/api/compass.md): Layered YAML configuration with per-environment directories, `SUMMER_` environment overrides, embedded plugin defaults and dot-path access.
- [conga](/docs/api/conga.md): Background jobs on River over the shared Postgres pool: transactional dispatch, a `summer_jobs` progress record, in-process or dedicated workers, and a wall-clock scheduler.
- [festival](/docs/api/festival.md): Typed, synchronous event bus with listener priorities, payload collection and stop-when-handled dispatch.
- [fetchguard](/docs/api/fetchguard.md): Guarded outbound HTTPS fetcher that blocks private and reserved addresses and enforces host, size and timeout limits.
- [flare](/docs/api/flare.md): Web Push delivery with VAPID (RFC 8292) and aes128gcm payload encryption (RFC 8291) behind a small Pusher interface.
- [lagoon](/docs/api/lagoon.md): Postgres data layer: the shared GORM connection, per-plugin migrations, model helpers and file attachments.
- [lighthouse](/docs/api/lighthouse.md): Transport-neutral realtime: a publisher interface with pluggable drivers, subscribe-time channel authorization, and model broadcasts enqueued in the write transaction.
- [pact](/docs/api/pact.md): Capability interfaces that compiled plugins implement to contribute routes, config, migrations, middleware, commands, admin screens, translations, mail templates, jobs and scheduled commands.
- [party](/docs/api/party.md): Compiled plugin registry that orders plugins by their dependencies and runs their Register and Boot lifecycle.
- [phrasebook](/docs/api/phrasebook.md): Namespaced translation catalogs loaded from plugin YAML, with locale fallback, placeholder interpolation and CLDR pluralization.
- [postcard](/docs/api/postcard.md): Transactional mail from plugin-owned Markdown templates and layouts, delivered through a memory, log or SMTP driver.
- [surf](/docs/api/surf.md): HTTP routing for SummerCMS: collects plugin routes and named middleware into a `net/http` ServeMux with constraints, rate limiting, body limits, CORS and panic recovery, and provides the `serve` and `route:list` commands.
- [tide](/docs/api/tide.md): HTTP parity toolkit that records request and response fixtures from a reference backend, replays them against a new one and reports normalized differences.
- [towel](/docs/api/towel.md): Request-scoped actor, organization, collection and locale values carried through `context.Context`.
- [wire](/docs/api/wire.md): JSON response helpers and value types that keep API bodies byte-compatible with a PHP (WinterCMS/Laravel) backend.
- [wristband](/docs/api/wristband.md): An OAuth authorization server for MCP clients: RFC 8414 metadata, RFC 7591 dynamic client registration, the authorization-code flow with PKCE, consent operations and refresh-token rotation over application-supplied storage.