Source and dependency map
This is the maintainer map for the monorepo. Paths are relative to repository root. Component README files are entry points into the canonical documentation; source-adjacent fixture/theme instructions stay beside those assets where useful. The root AGENTS.md defines repository-specific HTTP identity rules.
Top-level layout
| Path | Purpose and implementation entry points |
|---|---|
| controller/ | Website API types, CRD/RBAC and Kubernetes reconciliation |
| frontend/ | Dependency-free read-only static server |
| cms/ | Auth, JSON API, filesystem store, renderer, publisher and theme/import/plugin systems |
| cms/editor/ | Browser application source, npm lockfile, unit tests and browser drivers |
| deploy/ | Portable core manifests and deliberately separate example site/credentials |
| docs/ | Customer guides for site owners and administrators |
| contributing/ | Development, architecture, integration contracts and historical planning |
| screenshots/ | Labelled tour of the browser interface |
| TODO.md | Prioritised open work |
| examples/ | Four plugins (Go/C/Rust/blocks), two standalone themes, per-package scripts and shared Docker packaging |
| scripts/ | Documentation checks, Orbit CRD sync and disposable WordPress database test |
| go.work / go.work.sum | Go workspace and workspace dependency checksums |
| .gitlab-ci.yml | Tests, security includes and inherited container-build jobs |
| LICENCE | Apache-2.0 license notice |
The optional gitignored orbit-deployments symlink points to an external deployment
repository; it is not required to build this checkout and must not be assumed
present when validating docs. Generated editor dist, node_modules and browser
test binaries are ignored build outputs. Do not document them as source inputs.
Controller
API types define Website spec/status.
The canonical CRD
is mirrored at deploy/01-crd.yaml. Keep the RBAC
copy in deploy consistent with controller/config/rbac as well.
controller/cmd/controller loads flags, starts controller-runtime and serves
wrapped metrics/probes. internal/controller/website_controller.go reconciles,
resources.go builds desired objects/defaults, validation.go checks hostnames
and auth Secrets, ipseity.go handles discovery/provisioning, and startup.go
enqueues existing sites. Tests use fake clients and schema/pruning checks.
Startup reconciliation retries and preserves existing names/PVC identity; image
arguments are not inferred from the controller's own image tag.
Dependencies are Kubernetes api, apimachinery, client-go and
controller-runtime, plus their transitive dependencies. The controller is not
standard-library-only. It requires Kubernetes credentials and RBAC at runtime.
Frontend
frontend/cmd/webserver starts public/admin listeners and shutdown. Internal
config parses flags/env, logging emits JSON, metrics renders Prometheus
text, and server handles file paths, MIME/metadata, conditions, ranges and probes.
It uses the Go standard library only and does not call Kubernetes, an IdP or
the CMS. See HTTP behaviour.
CMS backend
| Package | Responsibility |
|---|---|
cmd/cms |
Runtime flags, store/publisher/auth wiring, listeners and volume-preparation command |
internal/api |
Route registration, typed JSON/multipart handling, CSRF, SPA and browser integration fixtures |
internal/auth |
Secret loading, discovery, login state, encrypted/reference sessions, JWT/introspection verification and roles |
internal/store |
Durable source/settings/assets/themes/packages, menu normalization, snapshots and mutation recovery |
internal/publisher |
Source rendering/sanitization, Index/repeater expansion, snapshot publication, activation/history/retention/status synchronization |
internal/theme |
Embedded themes/samples, component rendering, bindings, validation and portable bundles |
internal/extension |
Plugin manifest/ZIP validation and bounded WASI renderer execution |
internal/wordpress |
WXR parsing, database read-only inspection, conversion and permalink mapping |
internal/volume, internal/fileio |
Ownership preparation and shared file/close handling |
internal/metrics, internal/buildinfo, internal/web |
Metrics, stamped version/Server header and embedded fallback page |
The actual dependency inventory is cms/go.mod. Main purposes: OAuth2/OIDC and JOSE; Goldmark Markdown; bluemonday plus CSS parser libraries; HTML-to-Markdown conversion; MySQL driver; wazero WASI execution; and supporting network/text/system packages. Keep dependency changes deliberate and review licenses/lockfiles rather than claiming the CMS has only three exceptions to stdlib.
The editor uses Tiptap for visual Markdown, GrapesJS for HTML/template editing, DOMPurify for browser input and Vite for static bundling. See editor internals for state, authentication recovery and test boundaries.
Where to change an interface
Update schema/types and mirrored manifests for Website changes; update runtime
flags plus configuration for binary settings;
update route/input handlers and API for HTTP contracts.
Keep shared contracts, source formats and user/operations
steps aligned. Changes to HTTP listeners must wrap authentication, errors and
admin endpoints in buildinfo.WithServerHeader, using that module's stamped
version, and include response-level acceptance/rejection checks.
For CRD sync with external Orbit use scripts/sync-orbit-crd.sh --check PATH;
without an external checkout use the canonical/portable manifests described in
upgrades. This script edits only the selected local
copy when run without --check; it does not commit or deploy.