procyon-core

README

procyon-core

Versioned runtime shared by applications created from the Procyon template.

Applications depend on this module instead of owning copies of the framework infrastructure. Upgrade an application with:

go get github.com/bartek5186/procyon-core@latest
go mod tidy
go test ./...

The application keeps ownership of domain models, stores, services, controllers, routes and migrations.

Plugin lifecycle

The public plugins package composes project-owned and installed compile-time plugins in one registry. It validates unique names, resolves Requires dependencies topologically, and runs migrations, capabilities, events, policies, routes, workers and reverse-order shutdown deterministically.

The base Plugin interface remains compatible with existing modules. Optional interfaces add DependencyDeclarer, CapabilityRegistrar, EventRegistrar, MigrationProvider and Starter. Dependencies supplies the shared database, logger, event bus, business metrics, UTC clock and capability registry.

Versioned plugin migrations use the shared plugin_schema_migrations ledger. Legacy plugins can keep implementing their own Migrate method. See the plugin runtime guide for the complete contract.

Runtime configuration is layered. config.Read loads the selected base JSON file and then composes plugin defaults from a sibling plugins.generated.json. Explicit plugins.<name> values in the base file override generated defaults. Each plugin keeps ownership of its typed config structure and decodes only its namespaced JSON value.

Typed application events

The public events package provides synchronous, typed communication between the application and compile-time plugins. It intentionally has no worker, queue or persistence. A durable publisher remains responsible for retrying a failed Publish call.

Applications create one bus, pass it to every plugin through plugins.Dependencies.Events, call plugin RegisterEvents, register application handlers, and call Seal before routes or background tasks start. Plugins must not publish before the bus is sealed.

Topics are versioned contracts such as payment.purchase.completed.v1. Handlers run sequentially, stop on the first error and must be idempotent. See the event bus guide for contracts, lifecycle and existing-project wiring.