// SPDX-License-Identifier: PMPL-1.0-or-later
= TOPOLOGY.md — Generation Guide
Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
:toc:
:sectnums:
== What Is TOPOLOGY.md?
A single-file visual map of any project's architecture and completion status.
It lives in the repo root and contains:
1. **ASCII architecture diagram** — the full system as it will look when complete
2. **Completion dashboard** — every component with a progress bar and status note
3. **Dependency graph** — what blocks what (the critical path)
4. **Update protocol** — how to keep it current
It is designed to be readable by humans, AI agents, and rendered cleanly on any
forge (GitHub, GitLab, Codeberg, Bitbucket).
== Why
- Gives any contributor (human or AI) an instant picture of the whole project
- Replaces "read 20 files to understand the architecture" with one glance
- The completion dashboard makes project health visible without running anything
- Works offline, no tooling required, just a text file
== How To Generate One
=== Option 1: Ask an AI agent
Use this prompt (works with Claude, Gemini, ChatGPT, or any LLM with repo access):
[source,text]
----
Read the entire repository and produce a TOPOLOGY.md file for the repo root.
The file must contain exactly three sections:
1. **System Architecture** — An ASCII box diagram showing the complete system
as it will look when finished. Use Unicode box-drawing characters
(┌ ┐ └ ┘ │ ─ ├ ┤ ┬ ┴ ┼), arrows (▲ ▼ ◄ ► → ←), and double lines
(═ ║) for boundaries. Show:
- All external services (DNS, CDN, gateways) at the top
- Application components in the middle
- Data layer (databases, caches, queues) below
- Repo infrastructure (CI, contractiles, SCM files) at the bottom
- Every box labelled, every connection labelled or obvious from context
- The diagram should be BESPOKE to this project, not generic
2. **Completion Dashboard** — A table in a code block listing every component
from the diagram. For each component show:
- Name (left-aligned, padded to 35 chars)
- Progress bar: 10 characters using █ (done) and ░ (remaining)
- Percentage (0% to 100% in 10% increments)
- A short note explaining the status
Group components by layer/concern. End with an OVERALL summary line.
3. **Key Dependencies** — An ASCII arrow diagram showing the critical path.
What must finish before what else can start.
Add a header comment with SPDX-License-Identifier and Last updated date.
End with an "Update Protocol" section explaining how to maintain the file.
Use the template at TOPOLOGY.md in rsr-template-repo as a structural reference,
but make the content completely specific to THIS project.
----
=== Option 2: Copy the template and fill it in
[source,bash]
----
cp /path/to/rsr-template-repo/TOPOLOGY.md ./TOPOLOGY.md
# Then edit: replace placeholders, draw the real architecture, fill the dashboard
----
=== Option 3: Batch generation across all repos
[source,bash]
----
# From the repos root, generate for every repo that lacks one
for repo in /path/to/your/repos/*/; do
if [ ! -f "$repo/TOPOLOGY.md" ]; then
echo "NEEDS TOPOLOGY: $(basename $repo)"
fi
done
----
Then feed each repo to an AI agent with the prompt above. Claude Code can do
this with a session per repo, or you can batch it.
== Conventions
=== Box-drawing characters
Use Unicode, not ASCII art. This renders correctly everywhere.
[cols="1,1", options="header"]
|===
| Character | Use
| `┌ ┐ └ ┘` | Box corners
| `│ ─` | Vertical / horizontal lines
| `├ ┤ ┬ ┴ ┼` | T-junctions and crosses
| `═ ║` | Double lines for major boundaries
| `▲ ▼ ◄ ►` | Directional arrows
| `→ ← ↑ ↓` | Thin arrows (alternative)
|===
=== Progress bars
Always 10 characters wide. Use full blocks only (no half-blocks).
[source,text]
----
░░░░░░░░░░ 0% Not started
█░░░░░░░░░ 10% Stub/skeleton exists
██░░░░░░░░ 20% Early work
███░░░░░░░ 30% Foundation laid
████░░░░░░ 40% Core logic started
█████░░░░░ 50% Half done
██████░░░░ 60% Most logic complete
███████░░░ 70% Working but rough
████████░░ 80% Needs polish/docs
█████████░ 90% Nearly done
██████████ 100% Complete and tested
----
=== Component naming
- Use the actual names from the codebase (file names, service names, tool names)
- Group by architectural layer, not alphabetically
- Include repo infrastructure (CI, contractiles, SCM files) as a layer
=== When to update
- After completing a component → change bar + percentage
- After adding a component → add row
- After architectural change → redraw diagram
- After major milestone → update overall percentage
- Always update the `Last updated` date
== Integration With Other RSR Files
TOPOLOGY.md complements but does not replace:
- **STATE.a2ml** — machine-readable state (tasks, blockers, next actions)
- **ECOSYSTEM.a2ml** — position in the wider project ecosystem
- **META.a2ml** — architecture decisions and design rationale
- **0-AI-MANIFEST.a2ml** — AI agent entry point and invariants
TOPOLOGY.md is the _visual summary_ for humans; the a2ml files are the
_structured data_ for tooling. Both should agree.
== Copyright
Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>