pk-modules

module
v0.18.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 30, 2026 License: Apache-2.0

README

pk-modules

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

Depends on. pk-core only within PlatformKit (plus modernc.org/sqlite for the reference stores). It does not depend on pk-shared or pk-runtime — an app supplies the host.

Go Reference CI

pk-modules is the starter OSS module pack for the open-source PlatformKit family. It ships small, self-contained business modules — tenant, user, auth, API key, content, notification, audit, admin, and health — that implement the public PlatformKit module contract end to end: an entity, a store.Store persistence port with a SQLite reference implementation, a service, and an HTTP handler. Each module is wired with functional options and composes into a host application through pk-core's dependency-injection bundle, so community modules can follow the same patterns while vertical, client, and hosted-operational modules live in Pro/private packs.

Install

go get github.com/septagon-oss/pk-modules@latest

Usage

package main

import (
	"context"
	"log"
	"net/http"

	"github.com/septagon-oss/pk-modules/pkg/tenant"

	// Register the reference SQLite driver (modernc.org/sqlite) under the
	// default "sqlite" name the modules open against.
	_ "modernc.org/sqlite"
)

func main() {
	// Construct a module backed by a SQLite database. The store auto-creates
	// its schema, so a fresh DSN is ready to use immediately.
	m, err := tenant.NewModule(tenant.WithSQLiteDSN("file:tenants.db"))
	if err != nil {
		log.Fatal(err)
	}

	// Drive the module through its public service port.
	ctx := context.Background()
	t := &tenant.Tenant{Slug: "example-org", Name: "Example Organization"}
	if err := m.Service().Create(ctx, t); err != nil {
		log.Fatal(err)
	}

	// Mount the module's CRUD handler onto any net/http server.
	http.Handle("/api/v1/tenants/", m.HTTPHandler())
	log.Fatal(http.ListenAndServe(":8080", nil))
}

Current Surface

  • pkg/tenant, pkg/user, pkg/auth, pkg/apikey — identity, access, and session primitives.
  • pkg/content, pkg/notification, pkg/audit — content publishing, in-app notifications, and append-only audit logging.
  • pkg/admin, pkg/health — a responsive, accessible reference admin and health/readiness reporting. Modules register an AdminResource contract with readable columns, typed fields, lifecycle actions, and allowed operations; the shell renders real tables and forms without a raw JSON editor or frontend build step.
  • Every data module exposes a store.Store persistence port plus a store/sqlite reference implementation built on modernc.org/sqlite (pure-Go, no cgo).
  • pkg/portslib — the shared port contracts modules consume explicitly instead of importing one another.

Version namespaces

Each module exposes two deliberately separate versions:

  • ReleaseVersion is the pk-modules release shown in catalog/runtime metadata. It is 0.4.0 for this review build.
  • ModuleVersion remains the module's port-contract version, so an unrelated release does not invalidate compatible third-party modules. Existing contracts remain at 0.0.0.

The schema-aware AdminRegistrar API is the exception because it replaces the older RegisterEntityCRUD interface. Its contract is 0.4.0; consumers should declare portslib.AdminRegistrarContractVersion instead of copying a version literal.

Verify

make verify   # go test + go vet + staticcheck + race

License

Apache-2.0. See LICENSE.

Directories

Path Synopsis
pkg
admin
Package admin implements the admin_management plugin module.
 Package admin implements the admin_management plugin module.
admin/static
Package adminstatic embeds the admin shell's static assets.
 Package adminstatic embeds the admin shell's static assets.
apikey
Package apikey implements the api_key_management business module.
 Package apikey implements the api_key_management business module.
apikey/migrations
Package migrations exposes the embedded api_key_management migration files as an io/fs.FS so application-level runners can replay them.
 Package migrations exposes the embedded api_key_management migration files as an io/fs.FS so application-level runners can replay them.
apikey/store
Package store defines the persistence contract for api_key_management.
 Package store defines the persistence contract for api_key_management.
apikey/store/postgres
Package postgres is the Postgres Store implementation for api_key_management backed by database/sql.
 Package postgres is the Postgres Store implementation for api_key_management backed by database/sql.
apikey/store/sqlite
Package sqlite is the default Store implementation for api_key_management backed by database/sql.
 Package sqlite is the default Store implementation for api_key_management backed by database/sql.
audit
Package audit implements the audit_management business module.
 Package audit implements the audit_management business module.
audit/migrations
Package migrations exposes the embedded audit_management migration files as an io/fs.FS so application-level runners can replay them.
 Package migrations exposes the embedded audit_management migration files as an io/fs.FS so application-level runners can replay them.
audit/store
Package store defines the persistence contract for audit_management.
 Package store defines the persistence contract for audit_management.
audit/store/postgres
Package postgres is the Postgres Store implementation for audit_management backed by database/sql.
 Package postgres is the Postgres Store implementation for audit_management backed by database/sql.
audit/store/sqlite
Package sqlite is the default Store implementation for audit_management backed by database/sql.
 Package sqlite is the default Store implementation for audit_management backed by database/sql.
auth
Package auth implements the auth_management business module.
 Package auth implements the auth_management business module.
auth/migrations
Package migrations exposes the embedded auth_management migration files as an io/fs.FS so application-level runners can replay them.
 Package migrations exposes the embedded auth_management migration files as an io/fs.FS so application-level runners can replay them.
auth/store
Package store defines the persistence contract for auth_management.
 Package store defines the persistence contract for auth_management.
auth/store/postgres
Package postgres is the Postgres SessionStore implementation for auth_management backed by database/sql.
 Package postgres is the Postgres SessionStore implementation for auth_management backed by database/sql.
auth/store/sqlite
Package sqlite is the default SessionStore implementation for auth_management backed by database/sql.
 Package sqlite is the default SessionStore implementation for auth_management backed by database/sql.
branding
Package branding turns stored tenant branding choices into per-tenant theme overlays for the PlatformKit design stack.
 Package branding turns stored tenant branding choices into per-tenant theme overlays for the PlatformKit design stack.
branding/migrations
Package migrations exposes the embedded branding_management migration files as an io/fs.FS so application-level runners can replay them.
 Package migrations exposes the embedded branding_management migration files as an io/fs.FS so application-level runners can replay them.
branding/store
Package store defines the persistence contract for branding_management.
 Package store defines the persistence contract for branding_management.
branding/store/sqlite
Package sqlite is the default Store implementation for branding_management backed by database/sql.
 Package sqlite is the default Store implementation for branding_management backed by database/sql.
content
Package content implements the content_management business module.
 Package content implements the content_management business module.
content/migrations
Package migrations exposes the embedded content_management migration files as an io/fs.FS so application-level runners can replay them.
 Package migrations exposes the embedded content_management migration files as an io/fs.FS so application-level runners can replay them.
content/store
Package store defines the persistence contract for content_management.
 Package store defines the persistence contract for content_management.
content/store/postgres
Package postgres is the Postgres Store implementation for content_management backed by database/sql.
 Package postgres is the Postgres Store implementation for content_management backed by database/sql.
content/store/sqlite
Package sqlite is the default Store implementation for content_management backed by database/sql.
 Package sqlite is the default Store implementation for content_management backed by database/sql.
contracttest
storecontract.go — conformance checks for the parts of the store contract that AssertTenantScoped does not reach: the list surface, tenant reassignment through Update, and lifecycle rows that must stop being listed.
 storecontract.go — conformance checks for the parts of the store contract that AssertTenantScoped does not reach: the list surface, tenant reassignment through Update, and lifecycle rows that must stop being listed.
health
Package health implements the health_management business module.
 Package health implements the health_management business module.
migrate
Package migrate gives modules a way to evolve their schema.
 Package migrate gives modules a way to evolve their schema.
modulecontract
Package modulecontract makes the module boundary executable.
 Package modulecontract makes the module boundary executable.
notification
Package notification implements the notification_management business module.
 Package notification implements the notification_management business module.
notification/migrations
Package migrations exposes the embedded notification_management migration files as an io/fs.FS so application-level runners can replay them.
 Package migrations exposes the embedded notification_management migration files as an io/fs.FS so application-level runners can replay them.
notification/store
Package store defines the persistence contract for notification_management.
 Package store defines the persistence contract for notification_management.
notification/store/postgres
Package postgres is the Postgres Store implementation for notification_management backed by database/sql.
 Package postgres is the Postgres Store implementation for notification_management backed by database/sql.
notification/store/sqlite
Package sqlite is the default Store implementation for notification_management backed by database/sql.
 Package sqlite is the default Store implementation for notification_management backed by database/sql.
portslib
Package portslib defines the shared port surfaces that pk-modules business modules use to expose admin pages, health checks, in-app notifications, translations, and configurable settings.
 Package portslib defines the shared port surfaces that pk-modules business modules use to expose admin pages, health checks, in-app notifications, translations, and configurable settings.
tenant
Package tenant implements the tenant_management business module.
 Package tenant implements the tenant_management business module.
tenant/migrations
Package migrations exposes the embedded tenant_management migration files as an io/fs.FS so application-level runners can replay them.
 Package migrations exposes the embedded tenant_management migration files as an io/fs.FS so application-level runners can replay them.
tenant/store
Package store defines the persistence contract for tenant_management.
 Package store defines the persistence contract for tenant_management.
tenant/store/postgres
Package postgres is the Postgres Store implementation for tenant_management backed by database/sql.
 Package postgres is the Postgres Store implementation for tenant_management backed by database/sql.
tenant/store/sqlite
Package sqlite is the default Store implementation backed by database/sql.
 Package sqlite is the default Store implementation backed by database/sql.
user
Package user implements the user_management business module.
 Package user implements the user_management business module.
user/migrations
Package migrations exposes the embedded user_management migration files as an io/fs.FS so application-level runners can replay them.
 Package migrations exposes the embedded user_management migration files as an io/fs.FS so application-level runners can replay them.
user/store
Package store defines the persistence contract for user_management.
 Package store defines the persistence contract for user_management.
user/store/postgres
Package postgres is the Postgres Store implementation for user_management backed by database/sql.
 Package postgres is the Postgres Store implementation for user_management backed by database/sql.
user/store/sqlite
Package sqlite is the default Store implementation for user_management backed by database/sql.
 Package sqlite is the default Store implementation for user_management backed by database/sql.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.