architecture-map

Architecture Map

Produce <repo>/architecture-out/architecture-map.json + .html. The JSON is the source of truth; the HTML is rendered from it by scripts/build.sh — never write HTML by hand.

0. Freshness gate (always first)

Which of the two shapes you are in decides everything below: a single repo (the working directory is itself a checkout — .git exists) or a multi-repo workspace (no .git at the root; the member checkouts are listed in .claude/project.json → repos[], and module paths are workspace-relative, <repo>/<path-inside-it>).

Single repo

HEAD=$(git rev-parse HEAD)
LAST=$(node -e "try{const v=JSON.parse(require('fs').readFileSync('architecture-out/architecture-map.json')).analyzedAtCommit;console.log(typeof v==='string'&&v.length>=7?v:'')}catch{console.log('')}")

• LAST == HEAD → report "architecture map is up to date (commit )" and STOP.
• LAST non-empty → incremental mode: git diff --name-only $LAST..HEAD → map changed paths onto existing modules[].path prefixes; re-describe ONLY touched modules, re-check only flows whose steps reference them; keep the rest.
• LAST empty → full analysis.

Multi-repo workspace

There is no single HEAD to compare against, so compare PER MEMBER against the map's optional analyzedAtCommits object ({"<repo>": "<sha>"}):

# One member per LINE — a member directory may contain spaces.
node -e "try{const r=JSON.parse(require('fs').readFileSync('.claude/project.json')).repos;if(Array.isArray(r))console.log(r.join('\n'))}catch{}" |
while IFS= read -r repo; do
  [ -n "$repo" ] || continue
  [ -e "$repo/.git" ] || { echo "$repo: not a checkout — skipping"; continue; }
  head=$(cd "$repo" && git rev-parse HEAD)
  last=$(node -e "try{const m=JSON.parse(require('fs').readFileSync('architecture-out/architecture-map.json')).analyzedAtCommits||{};const v=m[process.argv[1]];console.log(typeof v==='string'&&v.length>=7?v:'')}catch{console.log('')}" "$repo")
  echo "$repo $last $head"
done