README
¶
PlatformKit
PlatformKit is a Go foundation for building multi-tenant SaaS applications. Compose business modules, generate administration screens from resource schemas, and build custom workflows with typed web components.
The foundation includes tenant isolation, authentication, permissions, events, background jobs and audit trails. Reference modules add users, notifications, billing, content, files, sites and tasks. Your application chooses the modules and connects their dependencies explicitly in Go.
Try it locally
Install the Go version declared in go.mod, then run this command from a directory where you want to keep the application's data. The first start needs internet access to download dependencies and PostgreSQL:
go run github.com/septagon-oss/platformkit/apps/platformkit@main start --addr 127.0.0.1:8080
This starts the reference application from main, with its own PostgreSQL 16
database and an initial tenant. No separate database or message broker is needed.
The HTTP server listens only on your machine.
Open the sign-in page and use
admin@platformkit.localhost with the password printed in your terminal.
Keep that password: it is shown only when the administrator is first created.
After signing in, explore the administration screens and the
component gallery.
Product applications configure tenant storybooks to
show only the examples selected for the signed-in tenant.
An optional Storybook.js adapter adds Storybook's native
navigation and controls while rendering these same Go components.
Use platformkit.localhost in your browser because the host identifies the
tenant. Stop with Ctrl+C; starting again from the same directory reuses your
database and uploads under ./data. Use --data to choose another data directory
or --addr to change the listening address and port.
This is a local evaluation setup, not a production configuration. For a deployed application, pin a reviewed module version and supply your own configuration, database and service credentials. config.example.yaml describes the available settings; its defaults are for local development.
Build your application
Use PlatformKit as a versioned Go dependency and compose it with your own modules. The reference application shows how to connect module constructors and their typed dependencies. Start with the task module when adding a capability: its public contracts describe the behavior, while its implementation stays behind that boundary.
External services connect through the contracts their consumers require. For example, the included billing provider records charges but does not transfer money; connect a payment processor when your product needs to collect payments. Email delivery likewise requires an SMTP configuration.
Architecture explains composition, tenant isolation, authorization and migrations in more detail.
Build a screen
Start with the entity and presentation map
to reuse generated forms and typed components, and the presentation map
for what each ui package owns. Compose custom workflows with pages;
shared themes change colors and typography across both
generated and custom screens.
Page localization composes module-owned messages through Go's x/text catalogs. The reference sign-in page includes English and Portuguese; additional screens supply their own messages through the same page contract.
The web interface is server-rendered, with HTMX for interactions. ui.Compose produces the stylesheet from shared components and your own declarations; there is no separate CSS build step.
Design tooling provides source snapshots and experimental editor integration. It is not yet a complete editable design library or a page-and-flow prototyping solution.
Use the HTTP API
Sign in through POST /api/v1/auth/login and retain the session cookie for
authenticated requests. Resource routes live under /api/v1/<module>/<entities>;
send requests to the configured tenant host.
The local evaluation exposes interactive API documentation.
For a configured application, /docs and /openapi.json are available when
server.docs is enabled; they are public endpoints, so enable them deliberately.
GET /api/v1/admin/resources describes the resources available to an authorized
shell. GET /health and GET /ready report process and dependency readiness.
Contributing and project information
Contributing covers working from a checkout, test setup and review requirements; AGENTS.md guides coding agents.
See the changelog for versioned changes and security policy for private vulnerability reporting. LICENSE and NOTICE contain licensing and attribution.
Directories
¶
| Path | Synopsis |
|---|---|
|
apps
|
|
|
platformkit
command
Command platformkit is the reference application: one binary, one image, and two subcommands — `run`, which serves, and `bootstrap`, which creates the first tenant of an empty installation.
|
Command platformkit is the reference application: one binary, one image, and two subcommands — `run`, which serves, and `bootstrap`, which creates the first tenant of an empty installation. |
|
Package design is the application's colours and type, as the two themes it ships and the custom properties they render to.
|
Package design is the application's colours and type, as the two themes it ships and the custom properties they render to. |
|
kit
|
|
|
app
Package app assembles a running application from a configuration and a list of modules.
|
Package app assembles a running application from a configuration and a list of modules. |
|
config
Package config is the one configuration surface: a YAML file, the environment overrides, the overrides a composition passes to Load, and a check that nothing needed is missing or malformed.
|
Package config is the one configuration surface: a YAML file, the environment overrides, the overrides a composition passes to Load, and a check that nothing needed is missing or malformed. |
|
crud
Package crud is the five operations every tenant-owned resource needs.
|
Package crud is the five operations every tenant-owned resource needs. |
|
db
Package db owns database access.
|
Package db owns database access. |
|
db/dbtest
Package dbtest gives one test its own Postgres schema.
|
Package dbtest gives one test its own Postgres schema. |
|
entity
Package entity describes tenant-owned data and derives its field metadata.
|
Package entity describes tenant-owned data and derives its field metadata. |
|
entity/display
Package display is how a field's value reaches a person: the text a control carries, the word a screen shows, and the name a field is called by.
|
Package display is how a field's value reaches a person: the text a control carries, the word a screen shows, and the name a field is called by. |
|
events
Package events is the one door a module's events leave through.
|
Package events is the one door a module's events leave through. |
|
events/internal/delivery
Package delivery owns the retry ladder and retention shared by event adapters.
|
Package delivery owns the retry ladder and retention shared by event adapters. |
|
events/providers/memory
Package memory delivers committed events inside one process.
|
Package memory delivers committed events inside one process. |
|
events/providers/nats
Package nats provides the existing JetStream event transport.
|
Package nats provides the existing JetStream event transport. |
|
events/transport
Package transport describes committed event delivery without a database or broker.
|
Package transport describes committed event delivery without a database or broker. |
|
flags
Package flags evaluates optional product behavior.
|
Package flags evaluates optional product behavior. |
|
flags/providers/ofrep
Package ofrep connects flags to an explicitly configured OFREP endpoint.
|
Package ofrep connects flags to an explicitly configured OFREP endpoint. |
|
flags/providers/openfeature
Package openfeature adapts a selected OpenFeature SDK provider to flags.
|
Package openfeature adapts a selected OpenFeature SDK provider to flags. |
|
health
Package health is the two probes an orchestrator calls, and the checks behind the second one.
|
Package health is the two probes an orchestrator calls, and the checks behind the second one. |
|
httpx
Package httpx builds the single Huma API the application serves, records every operation the adapter mounts, and enforces that each one declares exactly one authorization: a permission, public, or any signed-in user.
|
Package httpx builds the single Huma API the application serves, records every operation the adapter mounts, and enforces that each one declares exactly one authorization: a permission, public, or any signed-in user. |
|
internal/syscap
Package syscap mints the one capability that opens cross-tenant work.
|
Package syscap mints the one capability that opens cross-tenant work. |
|
jobs
Package jobs runs the periodic work: the outbox relay, the outbox purge, and whatever a module schedules in its manifest.
|
Package jobs runs the periodic work: the outbox relay, the outbox purge, and whatever a module schedules in its manifest. |
|
limit
Package limit is one rate limit for every replica.
|
Package limit is one rate limit for every replica. |
|
locale
Package locale supplies language selection and message formatting contracts for web pages, workers and other Go applications.
|
Package locale supplies language selection and message formatting contracts for web pages, workers and other Go applications. |
|
locale/providers/xtext
Package xtext adapts an explicitly supplied x/text message catalog to locale.
|
Package xtext adapts an explicitly supplied x/text message catalog to locale. |
|
module
Package module defines what a module is.
|
Package module defines what a module is. |
|
problem
Package problem is the one error shape the API returns: RFC 9457 problem details (the revision of RFC 7807), served as application/problem+json.
|
Package problem is the one error shape the API returns: RFC 9457 problem details (the revision of RFC 7807), served as application/problem+json. |
|
rest
Package rest is an entity's projection onto HTTP: five routes, the commands beside them, and the one mapping from kit/crud's errors to statuses.
|
Package rest is an entity's projection onto HTTP: five routes, the commands beside them, and the one mapping from kit/crud's errors to statuses. |
|
tenancy
Package tenancy is the one tenant model and how a request carries it.
|
Package tenancy is the one tenant model and how a request carries it. |
|
tenancy/providers/topaz
Package topaz adapts the official authorizer client to tenancy.Policy.
|
Package topaz adapts the official authorizer client to tenancy.Policy. |
|
Package migrations owns the kernel's schema: the tenancy helper functions and the tenants and hosts they resolve, the outbox with its claims and dead letters, and the limits ledger.
|
Package migrations owns the kernel's schema: the tenancy helper functions and the tenants and hosts they resolve, the outbox with its claims and dead letters, and the limits ledger. |
|
modules
|
|
|
admin
Package admin is the shell: the pages a person sees, as opposed to the routes a program calls.
|
Package admin is the shell: the pages a person sees, as opposed to the routes a program calls. |
|
admin/internal
Package internal is the shell's implementation: one chrome, one frame, the five pages written by hand, the catalog, and the screens ui/screens generates for every resource kit/rest registered before this module was composed.
|
Package internal is the shell's implementation: one chrome, one frame, the five pages written by hand, the catalog, and the screens ui/screens generates for every resource kit/rest registered before this module was composed. |
|
audit
Package audit is the module manifest: what the kernel needs to know about the audit trail that it cannot learn from a function call.
|
Package audit is the module manifest: what the kernel needs to know about the audit trail that it cannot learn from a function call. |
|
audit/contracts
Package contracts is everything another module, an app or a test may know about the audit trail: the row, the query, the permission and the Service interface.
|
Package contracts is everything another module, an app or a test may know about the audit trail: the row, the query, the permission and the Service interface. |
|
audit/contracts/audittest
Package audittest is the conformance suite for contracts.Service, and a fake that passes it.
|
Package audittest is the conformance suite for contracts.Service, and a fake that passes it. |
|
audit/internal
Package internal is every implementation of the audit module.
|
Package internal is every implementation of the audit module. |
|
auth
Package auth is signing in: sessions, passwords, single sign-on, and the roles that decide what a caller may do.
|
Package auth is signing in: sessions, passwords, single sign-on, and the roles that decide what a caller may do. |
|
auth/contracts
Package contracts is everything another module, an app or a test may know about signing in: the session, the identity a caller has, the errors a login can fail with, and the Service interface.
|
Package contracts is everything another module, an app or a test may know about signing in: the session, the identity a caller has, the errors a login can fail with, and the Service interface. |
|
auth/contracts/authtest
Package authtest is the conformance suite for contracts.Service, a fake that passes it, and an OpenID Connect issuer a test can sign in against.
|
Package authtest is the conformance suite for contracts.Service, a fake that passes it, and an OpenID Connect issuer a test can sign in against. |
|
auth/internal
Package internal is every implementation of the auth module.
|
Package internal is every implementation of the auth module. |
|
billing
Package billing is the module manifest: what a tenant is paying for.
|
Package billing is the module manifest: what a tenant is paying for. |
|
billing/contracts
Package contracts is everything another module, an app or a test may know about billing: the two entities, the events, the permissions, the payment provider this module needs somebody else to satisfy, and the Service interface.
|
Package contracts is everything another module, an app or a test may know about billing: the two entities, the events, the permissions, the payment provider this module needs somebody else to satisfy, and the Service interface. |
|
billing/contracts/billingtest
Package billingtest is the conformance suite for contracts.Service, and a fake that passes it.
|
Package billingtest is the conformance suite for contracts.Service, and a fake that passes it. |
|
billing/internal
Package internal is every implementation of the billing module.
|
Package internal is every implementation of the billing module. |
|
content
Package content is the module manifest: the pages and posts a tenant's public site is made of.
|
Package content is the module manifest: the pages and posts a tenant's public site is made of. |
|
content/contracts
Package contracts is everything another module, an app or a test may know about content: the entity, the events, the permissions and the Service interface.
|
Package contracts is everything another module, an app or a test may know about content: the entity, the events, the permissions and the Service interface. |
|
content/contracts/contenttest
Package contenttest is the conformance suite for contracts.Service, and a fake that passes it.
|
Package contenttest is the conformance suite for contracts.Service, and a fake that passes it. |
|
content/internal
Package internal is every implementation of the content module.
|
Package internal is every implementation of the content module. |
|
file
Package file is the module manifest: uploaded bytes and the rows that name them.
|
Package file is the module manifest: uploaded bytes and the rows that name them. |
|
file/contracts
Package contracts is everything another module, an app or a test may know about files: the entity, the events, the permissions, the storage this module needs somebody else to satisfy, and the Service interface.
|
Package contracts is everything another module, an app or a test may know about files: the entity, the events, the permissions, the storage this module needs somebody else to satisfy, and the Service interface. |
|
file/contracts/filetest
Package filetest is the conformance suite for contracts.Service, a Storage in memory that the suite runs against, and a fake Service that passes it.
|
Package filetest is the conformance suite for contracts.Service, a Storage in memory that the suite runs against, and a fake Service that passes it. |
|
file/internal
Package internal is every implementation of the file module.
|
Package internal is every implementation of the file module. |
|
notification
Package notification is the module manifest: telling somebody something, in the application and optionally by mail.
|
Package notification is the module manifest: telling somebody something, in the application and optionally by mail. |
|
notification/contracts
Package contracts is everything another module, an app or a test may know about notifications: the entity, the notice, the events, the two interfaces this module needs somebody else to satisfy, and the Service.
|
Package contracts is everything another module, an app or a test may know about notifications: the entity, the notice, the events, the two interfaces this module needs somebody else to satisfy, and the Service. |
|
notification/internal
Package internal is every implementation of the notification module.
|
Package internal is every implementation of the notification module. |
|
site
Package site is the module manifest: the data a tenant's public site is made of, and none of the rendering.
|
Package site is the module manifest: the data a tenant's public site is made of, and none of the rendering. |
|
site/contracts
Package contracts is everything another module, an app or a test may know about a tenant's public site: the settings, the event, the permission and the Service interface.
|
Package contracts is everything another module, an app or a test may know about a tenant's public site: the settings, the event, the permission and the Service interface. |
|
site/contracts/sitetest
Package sitetest is the conformance suite for contracts.Service, and a fake that passes it.
|
Package sitetest is the conformance suite for contracts.Service, and a fake that passes it. |
|
site/internal
Package internal is every implementation of the site module.
|
Package internal is every implementation of the site module. |
|
task
Package task is the module manifest: what the kernel needs to know about tasks that it cannot learn from a function call.
|
Package task is the module manifest: what the kernel needs to know about tasks that it cannot learn from a function call. |
|
task/contracts
Package contracts is everything another module, an app or a test may know about tasks: the entity, the events, the permissions and the Service interface.
|
Package contracts is everything another module, an app or a test may know about tasks: the entity, the events, the permissions and the Service interface. |
|
task/contracts/tasktest
Package tasktest is the conformance suite for contracts.Service, and a fake that passes it.
|
Package tasktest is the conformance suite for contracts.Service, and a fake that passes it. |
|
task/domain
Package domain owns portable task decisions.
|
Package domain owns portable task decisions. |
|
task/internal
Package internal is every implementation of the task module.
|
Package internal is every implementation of the task module. |
|
tenant
Package tenant is the control plane: which customers exist, and which host belongs to which one.
|
Package tenant is the control plane: which customers exist, and which host belongs to which one. |
|
tenant/contracts
Package contracts is everything another module, an app or a test may know about tenants: the entity, the events, the permission and the Service interface.
|
Package contracts is everything another module, an app or a test may know about tenants: the entity, the events, the permission and the Service interface. |
|
tenant/contracts/tenanttest
Package tenanttest is the conformance suite for contracts.Service, and a fake that passes it.
|
Package tenanttest is the conformance suite for contracts.Service, and a fake that passes it. |
|
tenant/internal
Package internal is every implementation of the tenant module.
|
Package internal is every implementation of the tenant module. |
|
user
Package user is the module manifest: the people in a tenant.
|
Package user is the module manifest: the people in a tenant. |
|
user/contracts
Package contracts is everything another module, an app or a test may know about users: the entity, the events, the permissions and the Service interface.
|
Package contracts is everything another module, an app or a test may know about users: the entity, the events, the permissions and the Service interface. |
|
user/contracts/usertest
Package usertest is the conformance suite for contracts.Service, and a fake that passes it.
|
Package usertest is the conformance suite for contracts.Service, and a fake that passes it. |
|
user/internal
Package internal is every implementation of the user module.
|
Package internal is every implementation of the user module. |
|
web
Package web is the public site: what an anonymous visitor sees at the root of a tenant's host.
|
Package web is the public site: what an anonymous visitor sees at the root of a tenant's host. |
|
web/internal
Package internal is the site's pages: the home, one published page, and the two things a visitor sees when there is nothing to show.
|
Package internal is the site's pages: the home, one published page, and the two things a visitor sees when there is nothing to show. |
|
tools
|
|
|
designexport
command
Command designexport projects typed examples and verifies Go source edits.
|
Command designexport projects typed examples and verifies Go source edits. |
|
locbudget
command
Command locbudget counts tracked source lines per bucket and fails when a bucket exceeds its committed maximum.
|
Command locbudget counts tracked source lines per bucket and fails when a bucket exceeds its committed maximum. |
|
Package ui is the browser half of the application: one stylesheet and small browser controllers, served as static files beside the API.
|
Package ui is the browser half of the application: one stylesheet and small browser controllers, served as static files beside the API. |
|
components
Package web renders pk-ui component contracts to HTML with gomponents, styled entirely through tw class lists against the PlatformKit design system's role variables.
|
Package web renders pk-ui component contracts to HTML with gomponents, styled entirely through tw class lists against the PlatformKit design system's role variables. |
|
components/examples
Package examples captures component constructor invocations as typed examples and describes them: Props as JSON Schema, named slots, observed HTML and child occurrences, derived by reflection from the actual Go inputs.
|
Package examples captures component constructor invocations as typed examples and describes them: Props as JSON Schema, named slots, observed HTML and child occurrences, derived by reflection from the actual Go inputs. |
|
css
Package css is the CSS intermediate representation the stylesheet is built in: typed values, declarations, rules, custom properties and the two at-rules the design system uses.
|
Package css is the CSS intermediate representation the stylesheet is built in: typed values, declarations, rules, custom properties and the two at-rules the design system uses. |
|
document
Package document is an HTML document as values: what every page of a shell shares (Chrome), what a render may know about the caller (Request), what a handler returned (View), and Document, which puts them together around the body a frame arranged.
|
Package document is an HTML document as values: what every page of a shell shares (Chrome), what a render may know about the caller (Request), what a handler returned (View), and Document, which puts them together around the body a frame arranged. |
|
export
Package export is the design-tooling half of ui: content-addressed snapshots of the composed components (Export, ExportWithLayout), token export in the DTCG interchange format (ExportTokens, TokenExport.DTCG), typed proposals applied to source captures (ProjectProps, ProjectReplacement), and the Storybook a shell serves so a person can browse the same composition.
|
Package export is the design-tooling half of ui: content-addressed snapshots of the composed components (Export, ExportWithLayout), token export in the DTCG interchange format (ExportTokens, TokenExport.DTCG), typed proposals applied to source captures (ProjectProps, ProjectReplacement), and the Storybook a shell serves so a person can browse the same composition. |
|
forms
Package forms composes portable entity forms from detached presentation inputs.
|
Package forms composes portable entity forms from detached presentation inputs. |
|
icon
Package icon is the glyph set the components draw with: the regular-weight Phosphor subset this application uses, vendored as path data.
|
Package icon is the glyph set the components draw with: the regular-weight Phosphor subset this application uses, vendored as path data. |
|
page
Package page is how a shell turns a screen into an HTML document.
|
Package page is how a shell turns a screen into an HTML document. |
|
resource
Package resource renders the screens of a schema-described resource — the list, the detail and the two forms — from plain values: the entity's schema, the rows a handler read, and the words the request's locale chose.
|
Package resource renders the screens of a schema-described resource — the list, the detail and the two forms — from plain values: the entity's schema, the rows a handler read, and the words the request's locale chose. |
|
screens
Package screens generates the screens of any resource kit/rest registered, for any shell that mounts them: the list, the detail, the two forms, the two writes and the delete.
|
Package screens generates the screens of any resource kit/rest registered, for any shell that mounts them: the list, the detail, the two forms, the two writes and the delete. |
|
source
Package source verifies and persists bounded edits to captured Go properties.
|
Package source verifies and persists bounded edits to captured Go properties. |
Click to show internal directories.
Click to hide internal directories.