{"slug": "show-hn-archwhere-work-alongside-ai-coding-agents-on-an-architecture-map", "title": "Show HN: Archwhere – work alongside AI coding agents on an architecture map", "summary": "Developer Tapaskar released archwhere, an open-source tool that puts every AI coding agent's pull request on a declared architecture map and requires agents to keep that map current as a condition of merging. archwhere ships with zero dependencies and a single JSON file, and its `npx archwhere init` command drafts the model from a repository's directory structure, package.json workspaces and import edges, with `archwhere check` failing CI when the map goes stale and `archwhere check --fix` adopting unmapped files into the nearest component. The tool targets the supervision gap created by agents shipping roughly thirty PRs a week, a workload the author argues diff-by-diff review cannot scale to handle.", "body_md": "**Your AI coding agents ship thirty PRs a week. Do you know where they land?**\n\narchwhere puts every change — every PR, every task, every agent — on a **declared\narchitecture map**: which component it touches, whether that component is a\nsecurity zone, and what needs you *right now*. Then it goes further: the map\nbecomes the place you **talk to your agents**.\n\n*Mission control on a fictional product: the attention rail (security → blocked →\nneeds-attention → ready-to-merge), the component map with live badges, and a\nthread pinned to a component — answered by a coding agent, with its PR.*\n\nZero dependencies. One JSON file. Works with Claude, or any agent that can see GitHub.\n\nSupervising 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.\n\narchwhere inverts it: **your agents maintain the map as a condition of merging**\n(there's a `SKILL.md` that tells them how, and `archwhere check` fails CI when\nthe map goes stale). You read components, not diffs.\n\n```\nnpx archwhere init\n```\n\nThat **drafts the model from your repo itself** — directory structure,\n`package.json` workspaces, import edges — with guessed kinds (auth → security,\nui → product, scripts → ops), plus the PR-comment workflow and two agent\nlisteners. `archwhere check` passes from minute one; you rename and refine\ninstead of starting from a blank file. It also prints a prompt you paste to\nyour coding agent so *it* polishes the model by surveying the repo. The\ncold-start problem every architecture-as-code tool dies on? Automated.\n\nDaily driver:\n\n```\nnpx archwhere                    # what is my working tree touching?\nnpx archwhere --base origin/main # what does this branch touch?\nnpx archwhere check              # CI guard: model valid, no file unmapped, no stale glob\nnpx archwhere check --fix        # adopt unmapped files into the nearest component\nnpx archwhere heat               # which components churned most in the last 30 days?\nnpx archwhere doc --out ARCHITECTURE.md\nnpx archwhere mission            # the UI at http://localhost:4610\n```\n\nWhen an agent's PR adds files the model doesn't own, the PR comment doesn't\njust complain — it **suggests the exact patch** (adopt into the nearest\ncomponent, or create a new one), and `archwhere check --fix` applies it. Tell\nyour agents \"run `check --fix` and review the adopted globs\" and the map stays\nalive with no human bookkeeping.\n\nAdd the action (one of the files `init` writes):\n\n```\n- uses: tapaskar/archwhere@v1\n```\n\nEvery PR gets a comment: a component/kind/files table, security flags, and the system map with touched components highlighted — rendered natively by GitHub:\n\n```\nflowchart LR\n  web-app[\"Web app\"]\n  mobile-api[\"Mobile API\"]\n  admin-console[\"Admin console\"]\n  ticket-engine[\"Ticket engine\"]\n  auth[\"Auth & sessions\"]\n  search[\"Search\"]\n  notifications[\"Notifications\"]\n  billing[\"Billing\"]\n  llm-gateway[\"LLM gateway\"]\n  jobs[\"Jobs & queues\"]\n  ops[\"Ops & CI\"]\n  docs[\"Docs\"]\n  web-app --> ticket-engine\n  web-app --> auth\n  mobile-api --> ticket-engine\n  mobile-api --> auth\n  admin-console --> ticket-engine\n  ticket-engine --> search\n  ticket-engine --> notifications\n  ticket-engine --> llm-gateway\n  search --> jobs\n  notifications --> jobs\n  classDef core fill:#E8EEF9,stroke:#2F4AC0,color:#1F2433\n  classDef security fill:#FDE8E4,stroke:#C2410C,color:#1F2433\n  classDef feature fill:#FFF4E0,stroke:#B45309,color:#1F2433\n  classDef infra fill:#EFEFEF,stroke:#595959,color:#1F2433\n  classDef product fill:#E3F2EC,stroke:#0F7A5C,color:#1F2433\n  classDef ops fill:#F3E8F9,stroke:#7E3FA0,color:#1F2433\n  classDef docs fill:#F7F7F7,stroke:#8A8A8A,color:#1F2433\n  classDef other fill:#F2F2EF,stroke:#777,color:#1F2433\n  classDef touched fill:#F7B32B,stroke:#1F2433,stroke-width:3px,color:#1F2433\n  class web-app,mobile-api,admin-console product\n  class ticket-engine core\n  class auth security\n  class search,notifications,billing feature\n  class llm-gateway,jobs infra\n  class ops ops\n  class docs docs\n```\n\n`npx archwhere mission` serves a local UI where the map is the conversation surface:\n\n- **Attention rail** — security items, blocked decisions, PRs needing attention,\nPRs ready to merge (the Merge button uses*your* token; agents never merge).\n- **Click any component → open a thread.** Threads are GitHub issues labelled`component:<id>` (auto-created). Your agent answers; the reply appears on the map.\n- **Four lenses** — Structure / Changes / Heat / Runtime.**Heat** colours components by git churn over the last 30 days — where your\nagents are actually spending effort.**Runtime** colours them by live health\nfrom any endpoint you point`RUNTIME_URL` at, returning`{\"components\": {\"<id>\": {\"status\": \"ok|warn|bad\", \"lines\": [\"…\"]}}}` .\n\nThe bus is GitHub — archwhere never talks to an agent directly:\n\n| Your agent | Setup | \n|---|---|\n| **Claude** | `agent-reply.yml` (written by`init` ) answers`@claude` via the Claude GitHub App | \n| **Any agent with an API** | `agent-webhook.yml` POSTs each thread event (component, issue, body, HMAC) to`AGENT_WEBHOOK_URL` ; it replies with its own GitHub token | \n| **Anything already watching GitHub** | nothing to do — have it watch issues labelled `component:*` | \n\nWhich mention the UI appends is yours: `arch/mission.config.json → {\"agentMention\": \"@your-bot\"}` (env `AGENT_MENTION` overrides; `\"\"` disables).\n\nOne file, declared judgment — not an auto-extracted import hairball:\n\n```\n{\n  \"system\": \"Meridian\",\n  \"components\": {\n    \"auth\": {\n      \"name\": \"Auth & sessions\", \"kind\": \"security\",\n      \"provider\": \"Auth0 + RBAC\",               // shows on every surface: map, PR comment, docs, mission UI\n      \"paths\": [\"core/auth/**\"],                  // ** crosses dirs, * stays in one; longest match wins\n      \"watch\": [{ \"pattern\": \"session|token|rbac\", \"note\": \"security review\" }],\n      \"deps\": []\n    }\n  },\n  \"lanes\": [[\"web-app\"], [\"auth\"]],               // optional; defaults to kind grouping\n  \"flows\": { \"signup\": { \"name\": \"…\", \"actor\": \"…\", \"steps\": [{\"from\": \"web-app\", \"to\": \"auth\", \"label\": \"SSO\"}] } }\n}\n```\n\nKinds: `core · security · feature · infra · product · ops · docs`. `flows` are\nyour C4-style dynamic views — the process layer above the components. The full\nexample: [`examples/meridian/architecture.json`](https://github.com/tapaskar/archwhere/blob/main/examples/meridian/architecture.json).\n\n`npx archwhere ir` compiles the model into [Archify](https://github.com/tt-a1i/archify)\nIR — an animated signal-flow system diagram with trust boundaries and guided\nviews per flow, plus one numbered diagram per flow. Render with Archify's CLI.\n\n[`SKILL.md`](https://github.com/tapaskar/archwhere/blob/main/SKILL.md) is the agent's side of the contract: place work on the map\nbefore coding, extend the model when adding modules, update flows when changing\nuser-visible processes, keep `archwhere check` green. Works as a Claude Code /\nagent skill, or paste it into your agent's instructions.\n\n|  | maps PRs | visual | agents maintain it | talk to agents on it | \n|---|---|---|---|---|\n| CODEOWNERS / labeler | ✓ | — | — | — | \n| Structurizr / IcePanel | — | ✓ | — | — | \n| dependency graphs | ✓ | hairball | n/a | — | \n| **archwhere** | ✓ | ✓ | ✓ | ✓ | \n\nFrom stranger to agent-replies-on-the-map in under twenty minutes — the full\nfunnel, stage by stage: [docs/ONBOARDING.md](https://github.com/tapaskar/archwhere/blob/main/docs/ONBOARDING.md).\n\nMIT © Tapas Kar. Built with and for AI coding agents — this repo's own model\nlives in [`arch/architecture.json`](https://github.com/tapaskar/archwhere/blob/main/arch/architecture.json), of course.", "url": "https://wpnews.pro/news/show-hn-archwhere-work-alongside-ai-coding-agents-on-an-architecture-map", "canonical_source": "https://github.com/tapaskar/archwhere", "published_at": "2026-10-31 05:46:30+00:00", "updated_at": "2026-10-31 06:18:39.496242+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "artificial-intelligence"], "entities": ["archwhere", "Tapaskar", "Claude", "GitHub", "Structurizr", "IcePanel", "CODEOWNERS"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-archwhere-work-alongside-ai-coding-agents-on-an-architecture-map", "markdown": "https://wpnews.pro/news/show-hn-archwhere-work-alongside-ai-coding-agents-on-an-architecture-map.md", "text": "https://wpnews.pro/news/show-hn-archwhere-work-alongside-ai-coding-agents-on-an-architecture-map.txt", "jsonld": "https://wpnews.pro/news/show-hn-archwhere-work-alongside-ai-coding-agents-on-an-architecture-map.jsonld"}}