05 — Site Architecture

Page-by-page IA for graphs.sgit.ai, with the source document behind each page and its publish status.

Status key: ✅ publishable near-as-is · ✏️ needs framing or light edit · ✍️ must be written fresh · 🔗 links out to an existing live artefact

Founder briefs abbreviated as briefs/. Concept references (C1…C30) are defined in 02__concepts-index.md.

The shape

The site follows the sibling-site pattern (/thesis/ → /method/ → /documents/ → /admin/) but adds a progressive-depth spine, because the founder's brief is explicitly "initial concepts, and then more, and then more."

Argue that spine from the corpus itself, using quote 35:

"this is just a question of altitude, like if you see something from a very high altitude you just see the city walls, and as you zoom in you start to see roads and buildings, and eventually people and cars."

That makes the navigation a demonstration of the thesis (C13, C22) rather than merely a choice — the same self-consistency that makes sgit.ai's "this site is served from an encrypted vault" line land.

graphs.sgit.ai
├── /                       The one-sentence claim + the three altitudes
├── /start/                 ALTITUDE 1 — the city walls (5 pages)
├── /grammar/               ALTITUDE 2 — the rules you can apply tomorrow (5 pages)
├── /depth/                 ALTITUDE 3 — the full argument (8 pages)
├── /examples/              Real worked graphs, with real numbers
├── /maps/                  Wardley maps as graphs
├── /infographics/          The visual library
├── /glossary/              Plain-language vocabulary  ← explicitly requested
├── /shipped/               What is built vs what is argued
├── /origins/               Where we came from — the ten-phase arc
├── /network/               Bridges to sgit / pki / nhi / sg-sentinel
├── /documents/             Raw markdown source of truth
├── /admin/{comms,versions,index}
└── /llms.txt               The agent surface — see 06__house-style

/ — the front page

Job: make a graph-literate reader curious and a newcomer unafraid, in under 200 words.

/start/ — Altitude 1: the city walls

Five pages. No jargon before it is earned. Every one of these is publishable near-as-is from library/concepts/v0_4_0__thinking-in-graphs.md — subject to the licence resolution in G8.

Diagram to build: the Task-42 typed-graph tree (thinking-in-graphs.md lines 468–487) as interactive SVG. It teaches the whole thesis in one picture.

/grammar/ — Altitude 2: rules you can apply tomorrow

Five pages. Short, rule-shaped, immediately usable — this is also the section an agent will consume, so keep it dense and pasteable.

Ship alongside: .issues/config/node-types.json and .issues/config/link-types.json as a downloadable, actually-running example schema — 12 node types, 10 verb/inverse pairs with domain/range constraints, 71 live nodes. ⚠️ And narrate the honest tension: the repo's own link-types.json ships a relates-to pair, which its ontology brief forbids. Own it on the page.

/depth/ — Altitude 3: the full argument

Eight pages. This is the "then more, and then more" tier.

Then a "more" shelf for C18 (messages as transformations), C19/C20 (projections; every paragraph is a graph), C22 (decompilation), C27–C30. Sources in 02__concepts-index.md.

/examples/ — real worked graphs

The proof section. Each page: the problem · the graph (node/edge counts, types) · what the graph shows that a table cannot · the raw data · the source brief.

The live demo to build: /examples/your-own-risk-graph/ — six questions, answers typed as fact/opinion/hypothesis/evidence, localStorage only, no backend, no account, no LLM required. Watch your own risk graph build itself. Source: briefs/06/24/risk-acceptance-and-reviews/v0.33.34__dev-brief__...personal-risk-acceptance-scenario...md. This is the single most valuable thing the site could ship beyond prose.

⚠️ Not on the site: the Odysseus case study (names a real product, needs a legal read) and the LinkedIn network CRM (real personal network data).

/maps/ — Wardley maps as graphs

Argue the connection first (C25): a graph says these things are connected; a map adds where they sit — connectivity says what relates, position says what to do.

/infographics/ — the visual library

nhi.sgit.ai's infographics page currently reads "Awaiting resources." This site should be where that changes. Full plan in 04__visual-assets-and-infographics.md Part C. Structure: the slides/slide-NN-name/{_page.json, brief.md, infographic.png} shape, prompt beside output, so every image is regenerable and auditable — the same provenance discipline the site argues for.

/glossary/ — ✍️ written fresh, explicitly requested

The founder's own ask (quote 34): users "don't know about semantic graphs, don't know about ontologies… we also need to explore different UIs, and different ways to name this." The corpus contains exactly one terminology table — concept / term / taxonomy / ontology / semantic field / concept scheme — buried in briefs/08/06/voice-debrief/v0.33.56__...concepts-not-words...md. Start there, expand, and give each term a plain-English alternative alongside the technical one. Naming is a design problem here, not a documentation one.

Also missing and referenced-but-absent: the corpus glossary cited by Appendix A of the 28 Jul brief as the authority on edge-grammar discipline, listing the established edge set (connected_to, observed_on, backed_by, measured_by, grants, reaches, enables, exposes, gives_rise_to, protected_by, conditional_on, defeated_by, owned_by, accepted_by, underwritten_by). No such file exists in this repo. The website should either import it or become it.

/shipped/ — what is built vs what is argued

Non-negotiable. The sibling sites' credibility rests on this separation, and this site's subject matter is overwhelmingly design.

Ships and is verifiable by reading code: the SGit vault commit DAG (content-addressed, multi-parent, tree-per-directory, HMAC-derived deterministic refs, real wave-BFS merge-base, three-way merge, working two-track visualiser with inline-SVG fork/merge arcs) · a graph of graphs via *.link.json typed edges pinnable to a commit · a read-only DAG query API exposed to untrusted sandboxed apps (sg.history.*) · a live typed property graph (.issues/, 71 nodes / 141 edges) · the three published vaults.

Does not exist anywhere in the repo: MGraph-DB as a dependency · any graph database · browser SPARQL/Cypher · RDF/JSON-LD in code · the semantic risk ontology as a schema file · the path-query language · commit signing (commit_v2.signature is written and only ever null).

The honest sentence: "We ship a hand-written content-addressed object graph in the browser. We do not use a graph database, and we say so in our own architecture notes."

Best supporting document: briefs/03/17/vault-redesign/v0.16.3__arch-note__four-layer-model.md (1,791 w) — "what we've built is not fundamentally an encryption system. It is a content-addressed, portable, storage-agnostic version control protocol." ✅ publishable as-is, and it carries its own honest caveat.

⚠️ Two corrections to inherit rather than repeat: library/skills/use_sgit-and-vaults/SKILL.md says object IDs are "SHA-256 of plaintext" — the code hashes ciphertext. And sgraph_ai__website/.../sg-vault-primitives.html implies attributability that commit signing does not currently provide.

/origins/ — where we came from

The ten-phase narrative arc is fully written in 01__the-thesis.md §K, with dates and paths. Each phase links to 2–3 primary-source markdown twins under /documents/.

Include a /origins/paths-not-taken/ page: the Issues-FS Lexicon package, cross-artifact compatibility testing (the most developed unimplemented idea in the corpus), MGraph-DB as the store ("for now let's keep it simple"), the Ontologist role. This is the provenance discipline the network argues for, applied to itself — the same move pki.sgit.ai makes.

/network/ — the cross-site bridges

Each sibling gets a page saying what it covers and why the graph argument bears on it.

Reciprocally: ask each sibling site to add a /graphs/ bridge page pointing back. That is what finally gives the philosophy a linkable home — and it is the fix for the routing failure described in 00__BRIEF.md §1.

/documents/ — raw markdown, source of truth

Follow the pki.sgit.ai pattern exactly: raw .md files under /briefs/, rendered reader pages under /documents/, and the page framing that says the raw markdown is the source of truth and the rendered page is presentation — "the provenance discipline this project argues for, applied to itself."

Candidate set and tiers: 07__source-manifest.csv.

Build order

Restated from 00__BRIEF.md §7, with page targets:

1. ✍️ / + the thesis page (G1)
2. ✅ /start/ — five pages, near-as-is
3. ✅ /grammar/ — five pages + the downloadable .issues/ schema
4. ✅ /examples/ — browser isolation, 2FA, Article 26(5)
5. ✏️ /grammar/the-blob/
6. ✍️ /glossary/ (G4)
7. ✏️ /maps/ — render the 4 outstanding maps
8. ✏️ /depth/ — eight pages, two needing rewrites
9. ✅ /shipped/ — the honesty page
10. ✏️ /infographics/ — build the graph prompt library first

This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).

== briefs/06__house-style-and-conventions.md