Show HN: Archwhere – work alongside AI coding agents on an architecture map

Your AI coding agents ship thirty PRs a week. Do you know where they land?

archwhere puts every change — every PR, every task, every agent — on a declared architecture map: which component it touches, whether that component is a security zone, and what needs you right now. Then it goes further: the map becomes the place you talk to your agents.

Mission control on a fictional product: the attention rail (security → blocked → needs-attention → ready-to-merge), the component map with live badges, and a thread pinned to a component — answered by a coding agent, with its PR.

Zero dependencies. One JSON file. Works with Claude, or any agent that can see GitHub.

Supervising an agent workforce diff-by-diff doesn't scale. Architecture tools (Structurizr, IcePanel) assume a human architect maintains the model — so the model rots. CODEOWNERS and labelers map files to owners but carry no meaning.

archwhere inverts it: your agents maintain the map as a condition of merging (there's a SKILL.md that tells them how, and archwhere check fails CI when the map goes stale). You read components, not diffs.

npx archwhere init

That drafts the model from your repo itself — directory structure, package.json workspaces, import edges — with guessed kinds (auth → security, ui → product, scripts → ops), plus the PR-comment workflow and two agent listeners. archwhere check passes from minute one; you rename and refine instead of starting from a blank file. It also prints a prompt you paste to your coding agent so it polishes the model by surveying the repo. The cold-start problem every architecture-as-code tool dies on? Automated.

Daily driver:

npx archwhere                    # what is my working tree touching?
npx archwhere --base origin/main # what does this branch touch?
npx archwhere check              # CI guard: model valid, no file unmapped, no stale glob
npx archwhere check --fix        # adopt unmapped files into the nearest component
npx archwhere heat               # which components churned most in the last 30 days?
npx archwhere doc --out ARCHITECTURE.md
npx archwhere mission            # the UI at http://localhost:4610

When an agent's PR adds files the model doesn't own, the PR comment doesn't just complain — it suggests the exact patch (adopt into the nearest component, or create a new one), and archwhere check --fix applies it. Tell your agents "run check --fix and review the adopted globs" and the map stays alive with no human bookkeeping.

Add the action (one of the files init writes):

- uses: tapaskar/archwhere@v1

Every PR gets a comment: a component/kind/files table, security flags, and the system map with touched components highlighted — rendered natively by GitHub:

flowchart LR
  web-app["Web app"]
  mobile-api["Mobile API"]
  admin-console["Admin console"]
  ticket-engine["Ticket engine"]
  auth["Auth & sessions"]
  search["Search"]
  notifications["Notifications"]
  billing["Billing"]
  llm-gateway["LLM gateway"]
  jobs["Jobs & queues"]
  ops["Ops & CI"]
  docs["Docs"]
  web-app --> ticket-engine
  web-app --> auth
  mobile-api --> ticket-engine
  mobile-api --> auth
  admin-console --> ticket-engine
  ticket-engine --> search
  ticket-engine --> notifications
  ticket-engine --> llm-gateway
  search --> jobs
  notifications --> jobs
  classDef core fill:#E8EEF9,stroke:#2F4AC0,color:#1F2433
  classDef security fill:#FDE8E4,stroke:#C2410C,color:#1F2433
  classDef feature fill:#FFF4E0,stroke:#B45309,color:#1F2433
  classDef infra fill:#EFEFEF,stroke:#595959,color:#1F2433
  classDef product fill:#E3F2EC,stroke:#0F7A5C,color:#1F2433
  classDef ops fill:#F3E8F9,stroke:#7E3FA0,color:#1F2433
  classDef docs fill:#F7F7F7,stroke:#8A8A8A,color:#1F2433
  classDef other fill:#F2F2EF,stroke:#777,color:#1F2433
  classDef touched fill:#F7B32B,stroke:#1F2433,stroke-width:3px,color:#1F2433
  class web-app,mobile-api,admin-console product
  class ticket-engine core
  class auth security
  class search,notifications,billing feature
  class llm-gateway,jobs infra
  class ops ops
  class docs docs

npx archwhere mission serves a local UI where the map is the conversation surface:

• Attention rail — security items, blocked decisions, PRs needing attention, PRs ready to merge (the Merge button usesyour token; agents never merge).
• Click any component → open a thread. Threads are GitHub issues labelledcomponent:<id> (auto-created). Your agent answers; the reply appears on the map.
• Four lenses — Structure / Changes / Heat / Runtime.Heat colours components by git churn over the last 30 days — where your agents are actually spending effort.Runtime colours them by live health from any endpoint you pointRUNTIME_URL at, returning{"components": {"<id>": {"status": "ok|warn|bad", "lines": ["…"]}}} .

The bus is GitHub — archwhere never talks to an agent directly:

Which mention the UI appends is yours: arch/mission.config.json → {"agentMention": "@your-bot"} (env AGENT_MENTION overrides; "" disables).

One file, declared judgment — not an auto-extracted import hairball:

{
  "system": "Meridian",
  "components": {
    "auth": {
      "name": "Auth & sessions", "kind": "security",
      "provider": "Auth0 + RBAC",               // shows on every surface: map, PR comment, docs, mission UI
      "paths": ["core/auth/**"],                  // ** crosses dirs, * stays in one; longest match wins
      "watch": [{ "pattern": "session|token|rbac", "note": "security review" }],
      "deps": []
    }
  },
  "lanes": [["web-app"], ["auth"]],               // optional; defaults to kind grouping
  "flows": { "signup": { "name": "…", "actor": "…", "steps": [{"from": "web-app", "to": "auth", "label": "SSO"}] } }
}

Kinds: core · security · feature · infra · product · ops · docs. flows are your C4-style dynamic views — the process layer above the components. The full example: examples/meridian/architecture.json.

npx archwhere ir compiles the model into Archify IR — an animated signal-flow system diagram with trust boundaries and guided views per flow, plus one numbered diagram per flow. Render with Archify's CLI.

SKILL.md is the agent's side of the contract: place work on the map before coding, extend the model when adding modules, update flows when changing user-visible processes, keep archwhere check green. Works as a Claude Code / agent skill, or paste it into your agent's instructions.

From stranger to agent-replies-on-the-map in under twenty minutes — the full funnel, stage by stage: docs/ONBOARDING.md.

MIT © Tapas Kar. Built with and for AI coding agents — this repo's own model lives in arch/architecture.json, of course.