Architecture

The authoritative statement is ARCHITECTURE.md in the repository, which follows a request from the composition to the verification of a change; the eleven decisions behind it are the ADRs. This page is the map.

The maps

The maps are nested: one for the workspace, three for the system, and nine for its flows. Each is embedded below and opens full screen from the link under it; its JSON source is kept beside it in the programme record. Every map was authored from the code on 2026-09-06 and checked for containment at four desktop sizes from 1440×900 to 2048×1320. Inside a map, drag to pan, scroll to zoom, and use the guided views where a map offers them.

Level 0 — the repositories

The repositories and where each thing lives

The public foundation, the native shell and this site; the private catalog and clients; GitHub Actions, the image registry, the clusters, Postgres and JetStream.

Open the repositories and where each thing lives full screen · source platformkit-workspace in the record

Level 1 — the system

How the pieces compose

client.yaml names modules, main constructs them, the kernel serves them under a tenant transaction; one UI with three shells; the schema seam; the design export to an editor.

Open how the pieces compose full screen · source platformkit-composability in the record

The layers inside the public repository

kit/, modules/, ui/ and design/, apps/ and tools/, and which layer composes which.

Open the layers inside the public repository full screen · source platformkit-foundation in the record

The composed modules and who depends on whom

The flagship’s fourteen modules across three repositories and their Deps edges, in the order the registry constructs them.

Open the composed modules and who depends on whom full screen · source platformkit-modules in the record

Level 2 — the flows

Boot

config.Load, compose, app.New, the migrations, the boot gates and the split into web, worker and all.

Open boot full screen · source flow-boot in the record

One request

From the request host to the commit: headers, request id, tenant, the lazy transaction, the session, the declared authorization, the handler, row-level security, the outbox row and the buffered response.

Open one request full screen · source flow-request in the record

Events and jobs

From a committed outbox row through the relay and JetStream to a handler in the event’s tenant transaction; the scheduler and the module jobs.

Open events and jobs full screen · source flow-events in the record

The schema seam

One entity struct to five routes, seven generated pages, the resources JSON, the native shell’s screens and the OpenAPI document.

Open the schema seam full screen · source flow-seam in the record

Design

Tokens and class lists to one stylesheet; the gallery’s typed examples to a snapshot, the export tool and the OpenPencil foundation file.

Open design full screen · source flow-design in the record

A client

client.yaml and assets through the flagship’s loader and registry to a bootstrapped tenant with an admin and a storefront.

Open a client full screen · source flow-client in the record

The native shell

Sign in, keep the cookie, read the seam, derive the screens, call the same five routes.

Open the native shell full screen · source flow-mobile in the record

The start command

From nothing to a running application: an embedded Postgres, the role, the first tenant, the combined role, Ctrl+C.

Open the start command full screen · source flow-start in the record

Delivery

From a pull request through the gates to a tagged image with its SBOM and a cluster that pulls it.

Open delivery full screen · source flow-delivery in the record

Layout

Directory Holds

kit/

the kernel: db, tenancy, config, problem, httpx, module, crud, rest, events, jobs, health, limit, app

modules/

business modules, each contracts/ + internal/ + module.go: tenant, user, auth, admin, audit, notification, billing, content, site, file, task, and web, the public site

ui/

typed components with their gallery of typed examples, the class builder, the stylesheet IR and the CSS emitter, the icon set, the browser controllers, page (documents as values), screens (screens generated from schemas, and the resources catalog) and ui.Export, the design snapshot

design/

design tokens and the two themes, as struct literals

apps/

platformkit, the reference binary: start (its own database, one command), run with --role web|worker|all, bootstrap

tools/

locbudget, the line-budget ratchet; designexport, the snapshot of the design contract, and under it the OpenPencil tooling that turns the snapshot’s tokens and icons into a .fig file

migrations/

the foundation schema; each module carries its own SQL

deploy/

the Dockerfile

docs/adr/

the decisions, one number each

Budgets

Every bucket of source has a ceiling in loc-budget.json, and the number of first-party packages linked into the binary has one in packages-budget.json. A pull request that exceeds a ceiling fails; raising one is an owner commit with a written reason. The numbers are not copied into prose anywhere, this page included: run make check-loc and make check-packages for today’s.

The browser half

There is no CSS build, no node in the build and no framework. ui/components is forty-one functions of the form Button(ButtonProps) g.Node, each declaring the classes it can emit; ui/style resolves exactly those classes to rules against the custom properties design renders; ui.Compose folds the two, plus a consumer’s own lists and rules, into one Sheet served from memory. htmx is the only third-party byte the browser runs, beside four controllers of a few dozen lines. Every response carries a content security policy with a per-request nonce. The detail is in Components, pages and screens.

Verification

make check runs the build, vet and format checks, the test suite against real Postgres and NATS — which includes the boot validation of authorization declarations, the tenant isolation cases and the empty-database boot — the source and package budgets, the import boundary and tenant-setting ownership. make e2e separately drives the admin shell and a generated CRUD journey in a browser. CI runs both, plus govulncheck and the native design conformance suite under tools/designexport/openpencil; the release workflow checks the tagged tree before publishing an image and its SBOM. The delivery flow draws the gates in order. A type check proves types, a test proves its exercised cases and a journey proves its observed outcome; none alone proves production readiness.