pk-apps

README

pk-apps

Part of PlatformKit — the open-source Go backend for multi-tenant SaaS.

pk-apps owns PlatformKit's canonical application composition package. It connects pk-core, pk-modules, and pk-runtime into one importable starter without introducing a product domain or a second runnable application.

Choose one entry point

To run PlatformKit, clone the public front door:

git clone https://github.com/septagon-oss/platformkit
cd platformkit
go run .

To build a downstream product, import github.com/septagon-oss/pk-apps/pkg/starterapp and contribute application-owned modules through starterapp.WithModules:

err := starterapp.Run(
    ctx,
    starterapp.DefaultConfig(),
    starterapp.WithModules(yourModule),
)

Two reference implementations of that extension seam live under reference/. Both are intentionally outside pkg/: neither is installed by the starter, a product template, or another supported composition.

Reference	Shows
reference/custommodule	The smallest useful shape of the seam — one tenant-scoped widgets resource, two scopes, routes on the shared mux. Start here.
reference/polls	What a fully-formed domain module looks like — append-only migrations, a draft → published → closed → archived lifecycle, author ownership plus a moderator scope, an audit outbox committed atomically with each mutation, signed anonymous voter identity, per-network throttling, /metrics counters, and a public browser surface beside the JSON API.

A module enforces its own authorization. Whatever scopes it checks, it must also declare through ModulePlugin.APIKeyScopes — otherwise the starter will refuse to mint a key that could ever satisfy them.

What starterapp composes

The package assembles ten reusable OSS modules against one shared SQLite connection:

• tenant, user, authentication, and API-key management;
• content, notifications, and append-only audit;
• tenant branding, admin, and health surfaces;
• authenticated request identity, explicit API scopes, request limits, and extension OpenAPI discovery.

The canonical front door binds to loopback and installs local development bootstrap data. Configured and non-development environments fail closed without an explicit administrator password.

Product workflows, client modules, hosted deployment state, and commercial capabilities belong outside this repository.

Verify

make verify

For architecture, configuration, security, and extension guides, use the PlatformKit documentation hub.

License

Apache-2.0. See LICENSE.