An architecture map your organisation can't forget to update. Point it at a GitHub org and a Node pipeline reads each repo's own metadata — tooling versions, internal and external dependencies, endpoints, deploy targets, test footprint, ownership — into JSON, which a React Flow app renders as a clustered, filterable diagram.
There is no central spreadsheet. A repo appears on the map, correctly, because its owner curated it on GitHub: a description, a few topics, a couple of custom properties. Nothing to keep in sync by hand, and the map can't quietly rot into fiction.
This repo ships with a synthetic demo estate (the fictional Meridian Labs), so
npm run dev shows a working map before you've configured anything.
The demo estate — open it live. Every card, edge and chip above was derived by the pipeline from the repos themselves; only the cluster names and colours are configuration.
- A graph of components, clustered by team, with dependency, service-link and deploy edges.
- A Component Inventory — the same data as a sortable table, a per-application matrix, and an integrations list.
- Drill-down into a client: its screens (routes) and the backend endpoints each one calls.
- Golden Path compliance: every repo scored against your engineering standards, tracked over time, with a curated log of accepted deviations.
- Health: stale repos, dependency-version drift, open security alerts, failing CI.
- Shareable URLs and embeddable slices — the whole view lives in the URL, so any filtered slice can be framed in a wiki page.
npm --prefix viz ci
npm run hooks # once per clone: refuse commits that put real data over the demo
npm run dev # the demo estate, at http://localhost:5173Then point it at your own org:
- Fork this repo and enable Pages (Settings → Pages → Source: GitHub Actions).
- Clone the repos you want mapped next to this one (or set
ATLAS_REPOS_DIRto the folder holding them). The pipeline reads those clones, and GitHub metadata (topics, renames) through yourghlogin, so read access to the repos is all it needs. - Scope it to your org:
export GITHUB_ORG=your-org. Unset, every cloned repo with a remote is mapped. Optional:BACKEND_REPOSfor backends beyond the auto-discovered ones. - Curate your repos with
type-*/status-*/owner-*/app-*topics — seedocs/repo-maintenance.mdfor the owner's checklist anddocs/topic-schema.mdfor the field reference. A repo joins the map as soon as it has atype-*topic. - Make it yours: copy
config.template.jsonoverconfig.jsonand set the title, yourclusterstaxonomy,internalScopes, anduiPackages. Most of it is also editable in-app via ⚙ Settings. - Run
npm run regenerateagainst those clones, then commit the refreshed data and push tomain;pages.ymlpublishes it.
Replacing the demo data.
npm run regenerateoverwrites the committedfe-architecture*.jsonandgithub-meta.jsonwith your own estate. The demo's curated overlays —backend-extra.json,repo-extra.json,inventory-extra.json,integrations.csv,third-party-meta.csv,golden-path/— are yours to edit; each file documents its own shape in a_commentfield.This repo's
config.jsonsetsdemoDataOrg, so the pre-commit hook (npm run hooks) and CI refuse to commit data files that describe any other estate. Copying the template overconfig.json(step 5) drops it, which is what a fork committing its own data wants.
Everything org-specific lives in config.json, fully documented in
config.template.json. Nothing is required — each field falls back to a
sensible default, and an unset field means "this doesn't apply to my estate" rather than "broken".
The ones worth setting first:
| Field | What it does |
|---|---|
clusters |
Your team taxonomy. Drives the graph's lanes, the Group filter, and the region colors. Unset, everything lands in one centre lane. |
internalScopes |
The npm scopes your org publishes under — what counts as an internal-dependency edge. |
uiPackages / uiHubFolders |
Your design system. Consumers collapse onto one hub card, and version drift against it is drawn. |
owners / applications |
Your team and application vocabulary. Both are open — an undeclared topic is accepted and auto-titled, so declare one only when the automatic title is wrong. |
guard |
Coverage tripwires for a regenerate run. Set them once your map looks right. |
apiDomains |
Your own API domains, so a CDN link isn't mistaken for an endpoint. |
| Path | What it is |
|---|---|
scripts/ |
The data pipeline (gather → parse → assemble) that produces the JSON below |
scripts/repos.mjs |
Repo discovery — auto-discovered from local clones; org membership read from each clone's own remote.origin.url; Java backends (no package.json) discovered separately for backend-scan.mjs |
scripts/_paths.mjs |
Portable paths (override the checkout dir with ATLAS_REPOS_DIR) |
github-meta.json |
Component Inventory built live from GitHub — descriptions + type-/status-/owner-/app- topics. Written by scripts/github-inventory.mjs |
inventory-extra.json |
What can't live on a repo: dates, comments, display-name overrides, and components with no repo (third-party services) |
repo-extra.json |
Curated per-repo knowledge: hosts/APIs, non-npm SaaS, FE→BE notes, cloud name maps |
backend-extra.json |
Curated backend topology: hosts, FE→BE wiring, service edges, deploy targets |
integrations.csv |
Curated service-to-service REST/Kafka links. Both protocols are also derived from code, and a curated row for the same pair flips to verified |
third-party-meta.csv |
Vendor, auth, criticality and hosts for third-party services |
fe-architecture.json |
Core model: repos, kinds, deps, endpoints, deployments, validation, inventory |
fe-architecture-extras.json |
Enrichment: purposes, ownership, test footprint, screens |
config.json |
Your configuration — see above |
viz/ |
The React Flow + Vite app |
viz/src/graph.js |
Graph and cluster layout |
golden-path/ |
Compliance scoring: the rules, the history of past runs, and the decision log |
server/server.mjs |
Token-gated /data API + static viz server (built by the Dockerfile) |
infra/ |
keycloak.md (login) + hosting.md (self-hosting) |
.github/workflows/ |
ci.yml, pages.yml (build + deploy), curation-report.yml (weekly backlog) |
npm run dev # viz dev server (proxies the live model + Regenerate/Publish)
npm run regenerate # re-run the whole pipeline against your local clones
npm run build # build the viz and bake data into published/
npm run guard # sanity-check the generated data (CI runs this before committing)
npm test # pipeline + graph + schema testsRepos are auto-discovered: any sibling checkout under the parent directory that's a git repo
with a package.json is picked up. Java backends have none, so they're discovered separately and
modelled from their build files. Set ATLAS_REPOS_DIR to point elsewhere and ATLAS_FETCH=1 to
git fetch each repo before reading. The pipeline reads local clones, so the data is only as
fresh as your checkouts. There is no scheduled refresh: run npm run regenerate, commit the
refreshed data, and push to main to redeploy.
-
GitHub Pages (
pages.yml) — builds and deploys on every change tomain. Self-contained; no external services. Pages is public, so the committed model goes out with the site, and the deploy makes you choose which you meant:- set the
ARCHMAP_PASSPHRASErepo secret (12+ chars) to encrypt it — readers type the passphrase once and the data is decrypted in their browser (scripts/encrypt-data.mjs); or - set the
PAGES_PUBLIC_DATArepo variable to1to publish it openly — right for a demo or a map you intend to be world-readable, wrong for a real internal estate.
With neither set the deploy fails and says so, rather than guessing.
- set the
-
Your own container (
Dockerfile+server/server.mjs) — serves the viz plus a token-validated/dataroute, which is real data protection rather than a passphrase. Seeinfra/hosting.md. -
Login is off by default. Set the
VITE_AUTH_*variables to gate access behind Keycloak — seeinfra/keycloak.md. Admins (theadminrole) additionally get ⚙ Settings, Dev mode, and Regenerate/Publish. Locally (npm run dev) auth is off and you have full admin access.
Switch between Graph, Matrix, Table and Integrations (top-left). Table is the full sortable Component Inventory; Matrix pivots components by application; Integrations lists the service links.
Group by (Graph view) switches which taxonomy the lanes follow — Team (your clusters),
Application (one lane per app-*), or Platform (applications rolled up via
config.platforms). Grouping is layout-only: the Group filter stays the team taxonomy, so the two
compose.
Two toolbar dropdowns separate adding detail from narrowing:
- Layers (additive) — Resources, Integrations (external SaaS), Deployments, Inventory catalog, and Service links (REST solid, Kafka dashed via a shared event-bus node).
- Filters (subtractive — OR within a dimension, AND across them) over Group, Status
(Current / Planned / Sunsetting / Removed) and Health (At-risk only). Non-matching cards are
hidden while the shared infrastructure they connect to survives; an empty dimension imposes no
constraint. Reset filters returns to the clusters'
defaultOnset.
Dev mode (admin-only) adds tooling, test and deploy detail. Hover a card to spotlight its relations; click a cluster to focus its members; click a card for full detail. Use search to highlight repos, the ⚠ health pill for pipeline warnings, and ⎙ Export to save a PNG.
Drilling into a client. Double-click a frontend card (or click View N screens →) to open its
screens (routes) and the backend endpoints each one calls, with clickable Swagger links. Shareable
via ?client=<repo-folder>. Screen data is extracted heuristically by scripts/screens-gather.mjs
(router parsing + import-graph tracing), so coverage is best-effort.
Embedding a slice. Set the filters to isolate what you want, then click </> Embed to get
an <iframe> snippet. It appends embed=1, which loads a chrome-less kiosk view — just the map
plus an "Open full map" link.
Cards flag stale repos (no commit in > staleDays), and design-system dependency edges turn red
when a consumer lags the latest referenced version. Clicking a node shows its Component Inventory
record; non-current components are styled (sunsetting dashed amber, planned dotted, removed
struck-through).
MIT.