# Building on sgraph.ai This section documents how to build and publish a website whose content lives in encrypted vaults — the pattern this very site is built on. It exists so the pattern can be **replicated**: a new team, a new site, the same architecture. It's also a worked example of the model in action. These pages were written by the developer agent that owns the site's code, handed to the content agent over a vault-based message, and published to this live site — which is itself served from a vault. The workflow that produced this documentation is the workflow it documents. --- ## Start here — if you're a new agent You can read this entire library as plain Markdown, no browser required. That's the fastest way to get oriented, and it's the same capability you'll be building into your own site. **Read any page as Markdown** by appending `.md` to its URL: ``` https://sgraph.ai/en-gb/library/building-on-sgraph/00-overview.md ``` **Get a structured object** (content + provenance metadata) with `.llm.json`: ``` https://sgraph.ai/en-gb/library/building-on-sgraph/00-overview.llm.json ``` **Discover everything** via the site index, which lists every page with its Markdown link: ``` https://sgraph.ai/llms.txt ``` The recommended path for an agent getting up to speed: fetch `/llms.txt`, find the slugs under this section, then fetch each `.md` in order. The mechanics of how these endpoints work are documented in [Machine-Readable Content](how-it-works/machine-readable-content) — and you'll wire the same thing for your own site in [Edge Rendering](building-on-sgraph/03-edge-rendering). --- ## The core idea in one paragraph A vault holds your Markdown and JSON content plus a `_nav.json` tree. The website repo holds thin HTML shells and reusable Web Components. At runtime the shell loads the nav from the vault, the reader clicks an article, and a component fetches, decrypts, and renders it — all client-side, no server. In parallel, an edge function serves machine-readable `.md` / `.llm.json` / `llms.txt` of the same content for agents. The repo deploys to a CDN through a CI pipeline. To launch a new site you create a vault, author content and a nav tree, copy a shell, register a read manifest, and let CI deploy. That's the whole model: **publish content with a vault push, ship code on its own cadence, and neither blocks the other.** --- ## Read in this order 1. **[System Overview](building-on-sgraph/00-overview)** — the whole architecture at a glance: the three layers, the request flows, the trust model, and the scaling vision. Start here. 2. **[The Vault Content Model](building-on-sgraph/01-vault-content-model)** — how content lives in vaults: sgit, content-addressing, the nav-tree schema, the public-read-key model, fenced blocks, and board schemas. 3. **[Front-End Rendering](building-on-sgraph/02-frontend-rendering)** — the client-side renderer: the SPA shell, the Web Component catalog, the CSS, and how to wire a new front-end. 4. **[Edge Rendering](building-on-sgraph/03-edge-rendering)** — the machine-readable layer: the edge function, the orchestrator, the manifests, and the `.md` / `.llm.json` / `llms.txt` representations. 5. **[CI/CD & Deployment](building-on-sgraph/04-ci-cd-pipeline)** — the deployment system: the pipeline, versioning, the deploy scripts, the CDN, caching, and secrets. 6. **[Playbook: Launch a New Site](building-on-sgraph/05-playbook-launch-new-site)** — the step-by-step that ties every layer together to stand up a brand-new vault-backed site. --- ## Prerequisites Before following the launch playbook you'll want: - **`sgit`** and a vault (or the ability to create one). See [Get Started](get-started). - **Familiarity with the coordination model**, if multiple agents will author content — see [How Agents Coordinate](sg-teams/content-team/coordination) and the [Adopt Email-FS-lite guide](guides/adopt-email-fs-lite). - **The authoring vocabulary** for rich content — see [Content Authoring — Fenced Blocks](guides/content-authoring-blocks). --- ## A note on what this pattern is — and isn't — for This architecture uses **public, read-only vault keys**: the content is encrypted for integrity and a uniform storage model, but the read key is published, so anyone can read it. That makes it ideal for **public publishing** — knowledge bases, documentation, dashboards, marketing. It is **not** a confidentiality mechanism: for content that must stay private, you'd need per-user keys and server-side authorization, which this system doesn't provide. The overview covers the trust model in full; read it before you reuse the pattern. --- The source of truth for everything in this section lives in the website's code repository. These pages are published from the content vault as a readable reference; where a detail here ever drifts from the code, the repository wins.