--- title: One architecture diagram for a project split across five repos, with Archify date: 2026-11-02 tags: [architecture-diagram, archify, multi-repo, documentation, claude-code] type: success status: n/a reproducible: true visibility: public stack: any; shown on a Python (AWS Lambda) + plain-JS project agent: Claude Code model: claude-opus-5-5 image: https://worklore.dev/images/97d82e68bbb8ecfed9c62d44768a8ca1.png image_alt: Archify diagram of worklore with the website, API, one Lambda with the MCP connector and skill-xray, two DynamoDB tables, and the sibling repos (skill, MCP Registry) as named boxes, with cards listing all five repos --- # One architecture diagram for a project split across five repos, with Archify My project lives in five repos: the site and server, the MCP connector's registry entry and tests, a skill that is one Markdown file, a scanner the server keeps a copy of, and a repo of articles. I wanted one picture of all of it, where every box links to the code that proves it. The catch is that the links between my repos are not code at all: the skill tells an agent to call the API with curl, and the scanner is copied in, not imported. A tool that follows imports sees five islands. I asked my agent to use [Archify](https://github.com/tt-a1i/archify). It draws from a JSON description and checks it, ending with a check in a real browser. What the docs don't say up front: **a diagram pins exactly one repository** (`meta.repository` takes one URL and one 40-character commit). So the approach is to pin the repo where the system runs, give every box from it line-level `sources`, show each sibling repo as a named box with no sources, and say what each sibling holds in a card. Two things failed first. My SSH remote was rejected for web links (`repository-evidence/links-unsupported`); the HTTPS form of the same repo fixed it. And my working tree had uncommitted edits, while Archify checks citations against the committed bytes, so line numbers have to come from `git show HEAD:`, not from the open file. The second run passed all four checks. 13 boxes, 12 arrows, 4 cards, 11 boxes linked to exact lines. ![The finished diagram: the pinned repo's parts linked to code, the sibling repos as named boxes, and the repo card underneath](https://worklore.dev/images/97d82e68bbb8ecfed9c62d44768a8ca1.png) Where my line is: Archify proves the cited lines exist at that commit. It does not prove what a card says. My card on "how stories get written" was wrong twice, from my agent's memory, until I asked. Have the agent check each card against the code. ## Reproduce this Prerequisites: Node 18+, git, Google Chrome (the last check opens the diagram in a real browser), and local clones of every repo you want on the picture. Your agent will need from you: which repo is where the system runs (it gets pinned); for each other repo, one line on what it holds and how it connects (copied in, called over HTTP, published to a registry); whether the pinned repo is public (if private, the source links open only for people with access). Steps: 1. Get Archify without installing it globally: `git clone --depth 1 https://github.com/tt-a1i/archify.git`, then `node archify/archify/bin/archify.mjs doctor` must end with "Archify is ready". (The official `llms.txt` install uses `npx skills add` and asks for its scope first; a clone touches nothing else.) 2. Have the agent read `archify/archify/SKILL.md`, `references/repository-authoring.md`, `references/authoring-defaults.md` and `examples/web-app.architecture.json` before writing anything. 3. Pin the main repo: `git rev-parse HEAD` and the origin in its HTTPS form (`https://github.com//.git`, not `git@github.com:…`) go into `meta.repository` with `"provider": "github", "link_mode": "web"`. Use `"link_mode": "local-only"` if you don't want web links. 4. For every box that lives in the pinned repo, add `sources` (at most 3 per box: `path`, `line`, `end_line`), with line numbers read from the commit: `git show HEAD: | nl -ba`. 5. For each sibling repo, add a box whose sublabel names the repo (for example "from worklore-mcp repo"), with no `sources`, and the arrow that says how it connects ("instructions", "listing", "copy of own repo"). 6. Add a card listing all the repos and what each holds. Keep things you deliberately left out in a "Not drawn" card. 7. Run from a working folder outside the repos: `node /archify/bin/archify.mjs finalize architecture /candidate.json /.html --repo-root --quality showcase --json` On a failure, apply the `supportedFixes` from the diagnostics, then rerun. When rerunning to the same output path after a browser check has run, add `--out-dir /review-`. 8. Check every card against the code before sharing; Archify does not check them. Verify: - The `finalize` JSON says `"status":"pass"` with `validate`, `deliver`, `check` and `browser-check` all `pass`. - Opening the HTML shows every repo: the pinned repo's parts as linked boxes, each sibling repo as a named box, and the repo card. - A box's source link opens the cited lines at the pinned commit (for a private repo, while signed in to it).