This page is the map of the machinery, and the map is one picture. Everything else in this wiki is a close-up of some part of it: Platform Internals walks the gitops repo, Security Model names the mechanism behind each boundary, CI and Builds and Preview Environments follow one change through the pipeline.

The one diagram

The picture follows your Forgejo theme. Both versions are generated from code that ships with the platform (docs/architecture/diagram.ts), with a check that no line crosses a box, so the picture and the system change together.

Deploying on Azure? The deployment view (dark) shows what deploy/azure/main.bicep provisions around this cluster and the operator's steps in order.

How to read it

• Zones are trust boundaries. Outside the platform; network entry; the Kubernetes cluster; and inside it, one namespace per app per environment. Every line that crosses a zone is a line the platform authenticates or authorizes.
• Solid boxes are required roles. Dashed boxes are optional. The platform runs without the optional ones.
• The small type under a name is the open standard that box implements. The name is what ships today; any implementation of that standard fits. Forgejo is git over HTTPS and SSH, Actions-compatible CI, an OCI registry and an OAuth2 / OIDC provider. Traefik is a Kubernetes Ingress. Flux is a GitOps reconciler. CloudNativePG is Postgres.
• Four flows, four line styles. Green, numbered 1 to 7: a request to an app. Black, lettered A to I: a change to an app. Amber dashed: identity. Plum dotted: integration points. The captions under the diagram spell out every step; they are repeated below.
• The amber chip marks every component that signs in with Forgejo.

Outside the platform

People reach apps in a browser over HTTPS. Developers work in git and pull requests. Your own AI agents, any MCP client, act as you through the platform API. Your identity provider can sign people in to Forgejo. Your systems, Microsoft Graph or any public HTTPS API, are reached from apps over outbound HTTPS. An AI model provider serves only the build crew. The last four are optional.

Network entry

DNS points at one of two doors. A load balancer exposes TCP 80 and 443, plus 2222 for git over SSH. Or a Cloudflare Tunnel: its connector dials out from the cluster, so no inbound port is open anywhere. Pick one.

Inside the cluster

Any conformant Kubernetes works: k3s on VMs (AWS, Azure, DigitalOcean, a VPS, on-prem) or AKS. Inside, five columns.

Control plane · Forgejo at https://git.open-platform.sh. Identity, orgs and teams as an OAuth2 / OIDC provider. Repos, issues, pull requests and webhooks. Actions CI on an isolated runner pool with no Docker daemon and no cluster token. The package registry that holds every image, cosign-signed, and every Helm chart. Repo permission is app permission: what you may do to an app's repo is what you may do in the app.

Platform API · MCP at https://mcp.open-platform.sh/mcp. Every tool acts as the caller, and Forgejo enforces the caller's permissions on every call. The API renders app overlays into gitops, answers CI at /ci/preview and /ci/sync-env, and keeps an audit log of every call. The AI build crew is optional: a dispatcher turns Forgejo webhooks into pull requests, with per-run scoped keys and a spend ledger. It idles until a model credential is set.

Desired state → cluster. The gitops repo holds one overlay per app per environment, with secrets sealed by SOPS to one sovereign age key. Flux converges the cluster to the repo every minute and writes a commit status on the gitops commit it applied. Kyverno enforces twelve admission policies. cert-manager issues every certificate, from Let's Encrypt or the platform's own CA.

Workloads. Production and previews have the same shape: a namespace <org>--<app>--<env>, the app from the template, its own Postgres when it declares one, PodSecurity restricted, default-deny network, a resource quota. Production serves https://<app>-<org>.open-platform.sh. A pull request's preview serves https://pr-<N>-<app>-<org>.open-platform.sh and is removed when the PR closes.

Observe. Prometheus with 60-day retention and Grafana, signed in with Forgejo. Postgres backups, WAL plus base, go to an S3-compatible store: in-cluster MinIO by default, an off-site mirror if you want one.

Traffic: a request to an app

1. A request to https://<app>-<org>.open-platform.sh.
2. DNS to your load balancer (80 and 443, plus 2222 for git over SSH), or to Cloudflare, which reaches the cluster through an outbound tunnel.
3. Traefik routes by host name.
4. Traefik asks the edge auth service (forwardAuth) before it forwards.
5. Edge auth verifies the sealed session cookie and the caller's Forgejo permission on the app's repo. No session means a Forgejo login (OAuth2).
6. Traefik forwards with verified X-Plat-User, X-Plat-Perm and X-Plat-Manage headers. Client-supplied copies were stripped first.
7. The app reads its own Postgres.

The app trusts those headers for one reason: it is reachable only through Traefik, and the middleware chain strips any X-Plat-* a client sends before the edge injects the verified set. Without X-Plat-User the app fails closed. Edge-header identity is the template's default; in-app Forgejo OAuth is the alternative.

Contribution: a change to an app

• A. A developer, or your agent through the platform API, pushes a branch and opens a pull request.
• B. CI on the isolated pool: lint, typecheck, test, build the image with rootless BuildKit, sign it with cosign.
• C. Push the image and the Helm chart to the registry.
• D. CI calls /ci/preview. The API checks the run's own token for push rights on this repo.
• E. The API commits a preview overlay to gitops.
• F. Flux converges the cluster to that gitops commit and marks it with a commit status.
• G. Kyverno checks the image signature and registry at admission (enforced once a signing key is provisioned) and fences the namespace with a quota and default-deny network. Kubernetes enforces PodSecurity restricted.
• H. The preview is live at its own URL, with its own database and OAuth app.
• I. Review on the live preview, merge, release. The same path pins production to a version tag.

Every step is a git commit, a webhook, or a tool call. Nothing moves outside the control plane.

Identity: one sign-in, inherited everywhere

Forgejo is the identity provider. Your own identity provider can be added as a Forgejo sign-in source over OIDC (Entra ID is scripted; any OIDC provider works), and local accounts stay for break-glass. Everything downstream signs in with Forgejo: the edge auth service, the platform API (OAuth2 PKCE or a personal access token), Grafana, and every app through its own OAuth app.

Authorization follows the same line. Teams and collaborator grants give a person a permission on a repo: read, write or admin. The edge collapses that permission into X-Plat-Perm, the app's manage surface unlocks at write and above, and the app's audit log records the verified actor, never a value the client supplied. Add someone to a team and they can reach the app; remove them and they cannot. There is no second user directory to keep in sync.

Integration: your systems, on your terms

An app reaches an external system the way IT expects. Credentials live in the repo's Actions secrets, which are write-only. The sync-env workflow seals them into the gitops overlay with SOPS, and they arrive in the running app as environment variables. Outbound HTTPS to public endpoints is open by default; private address ranges are blocked. For Microsoft Graph that means an app registration in your tenant: you grant the scopes, you see the consent, you revoke it there. See Secrets and Config.

Apps integrate with each other through contracts, not shared tables: a provider publishes its OpenAPI document and a typed client, and a consumer holds references. See get_contract in Connect Your Agent.

Only the build crew talks to the AI model provider. Anthropic is what ships and is tested; the crew harness takes its API endpoint from its environment, so a provider gateway or a brokered token can sit between the platform and the model.

What you can swap

Role	Standard	Ships today
Code, CI, registry, identity	git over HTTPS/SSH · Actions-compatible workflows · OCI Distribution · OAuth2 / OIDC	Forgejo
Cluster	Kubernetes	k3s or AKS
Ingress	Kubernetes Ingress	Traefik
Reconciler	GitOps	Flux
Admission policy	Kubernetes admission webhooks	Kyverno
Certificates	ACME DNS-01, or a private CA	cert-manager
Secrets in git	SOPS with age	SOPS + age
Database	Postgres	CloudNativePG
Metrics	Prometheus exposition	Prometheus + Grafana
Backups	S3 API	MinIO
Model provider	the harness's API endpoint	Anthropic

The named implementation is what the cold-start gate exercises. Swapping one is a platform change: a gitops commit, like everything else.

Where to go next

• Platform Internals: the gitops repo top to bottom, the Flux graph, secrets, TLS, the registry, the twelve policies.
• Security Model: each guarantee and the mechanism that enforces it.
• CI and Builds and Preview Environments: steps B to H in detail.
• Users, Teams and Access: how permission reaches an app.
• Reference: every URL shape, label, tool and environment variable.