plexsphere documentation

This documentation is organised by Diátaxis. It is split by what you need right now, not by which subsystem you are touching. Pick the quadrant that matches your situation — the question on the left is the one that quadrant answers.

Find your path

You are…	You want…	Go to
new to plexsphere	to learn it by doing, hand-held	Tutorials
getting a job done	the shortest correct steps for a task	How-to guides
looking something up	the exact contract of a surface	Reference
trying to understand	why it is built this way	Explanation

If you are unsure which you need, you almost always want a tutorial (if plexsphere is new to you) or a how-to (if you have a specific goal). Start there; each page links onward to the others.

The four quadrants

• Tutorials — learning-oriented lessons. Start with Set up your local plexsphere, then explore your first Domain, then build in your first Domain. A tutorial is a guided lesson with a guaranteed outcome; it makes every choice for you.
• How-to guides — task-oriented runbooks for operators and contributors: invite an operator, register a node, rotate the signing key, run migrations, exercise an HTTP surface. A how-to assumes you know what you want and gives you the shortest correct path to it.
• Reference — information-oriented, typed surfaces generated from the source of truth. Start with the API surface map for the tag-by-tag index of /v1; see also the plexctl CLI and the dev-stack reference.
• Explanation — understanding-oriented discussion. The architecture explains how the whole system fits together; the bounded contexts explain the domain model, invariants, and seams of each context.

Beyond the four quadrants

• Operations — cross-cutting operational runbooks for running plexsphere in production, spanning more than one bounded context. Start with operating across multiple regions — pinning tenants to regional management clusters, the region-scheduling and migration resolver, per-region ingress, and the region DNS model — and the failure modes and degradation runbook for how a replica rides out a single dependency outage.
• Contributing — the practical handbook for working on this repository itself: the CI pipeline, testing, the toolchain, and the docs authoring conventions. This is deliberately outside Diátaxis — it documents the project, not the product.
• Future directions — forward-looking architecture explorations that are not yet built, kept separate from the shipped contexts and reference so a proposal is never mistaken for a contract. Start with the federated relay fabric.

New to the docs themselves? Read how this documentation is organised before you add or move a page.