ArchLens - Solution Architecture Diagrams
A solution-architecture diagram of your repo, generated from the code and shown inside VS Code.
It answers questions like: What are the main components? How is the web frontend connected to the API gateway? What does the order service talk to, and over what? Which service owns the database?
- Layered diagram. Clients, frontend, edge (BFF / gateway), services and workers, then data stores, brokers and external systems, top to bottom.
- Labelled connections. Every arrow says what flows (for example "order requests") and over which protocol (REST, gRPC, SQL, AMQP, Kafka, ...). Dashed arrows are asynchronous.
- Built for big systems. A tier with many components wraps into several staggered rows instead of one very wide row. Each caller has its own arrow colour, and connection points are spread along a component's border so arrows don't merge into one thick line. Hover or click a component to light up only its own connections and fade the rest. The Labels button shows or hides arrow labels (the default hides them while zoomed far out).
- Click for detail. Select a component to see what it does, what it connects to, who uses it, which folders implement it and its key files (click a file to open it). Select an arrow to see exactly what flows over it.
- Search. Find any file or component by name. Picking a file opens it and highlights the component that owns it.
- Editable, reviewable skills. The diagram is drawn from plain Markdown skill files in
.solution-architecture/skills/. Generate them with your Copilot subscription, then correct, extend and commit them like any other file.
How to generate your architecture
Open the repo folder in VS Code. For a monorepo, open the monorepo root.
Sign in to GitHub Copilot (Accounts icon, bottom left). AI generation uses your Copilot subscription. No Copilot? Skip to Quick scan below.
Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run Solution Architecture: Open Diagram. A panel opens.
Click Generate in the panel. You can also run Solution Architecture: Generate with Copilot from the Command Palette. The first time, VS Code asks whether ArchLens - Solution Architecture Diagrams may use Copilot's language models. Choose Allow.
Watch the progress notification:
- Reading repository structure
- Identifying components
- Scanning code for connections… n/total files (runs locally, capped at 90 seconds)
- Working out how components connect
Expect roughly 30 seconds to a couple of minutes, depending on repo size. You can cancel at any time.
The diagram appears, and one skill file per component is saved in .solution-architecture/skills/. Commit these files to share the diagram with your team.
Quick scan (no AI). Click Quick scan (or run Solution Architecture: Generate (Quick Scan, No AI)) for a rough diagram built locally from package manifests, workspace dependencies and docker-compose. It needs no sign-in and sends nothing anywhere.
Check and correct the result. Connections are inferred, so compare them with what you know. To fix one, select the component, click Edit skill file, change its connects_to lines and save. The diagram updates immediately.
Generating again. Clicking Generate a second time asks for confirmation and then replaces all existing skill files, including your manual edits. Copy .solution-architecture/skills/ somewhere first if you want to keep them.
Troubleshooting
| Problem |
What to do |
| "No language model available" |
Install and sign in to GitHub Copilot, then try again. Or use Quick scan. |
| The Command Palette doesn't list Solution Architecture commands |
Run Developer: Reload Window once after installing. |
| Generation seems stuck on "Scanning code" |
That step stops by itself after 90 seconds and uses what it found. You can also cancel it. |
| The diagram has a wrong or missing arrow |
Edit connects_to in that component's skill file (see below). |
| The panel says "No architecture map yet" |
No skill files exist yet. Click Generate or Quick scan. |
| Only part of a multi-root workspace is mapped |
Only the first folder is mapped. Open the folder you want as the workspace root. |
How generation works
- Components. The model gets a summary of the repo (directory tree with file counts, the start of a few manifests, compose and
.env.example files, the root README) and returns the logical components: frontend, BFF, services, workers, shared libraries, plus databases, caches, queues and external systems when there is evidence for them.
- Evidence. The extension reads each component's own files and records where they mention another component (
paymentClient, PAYMENT_SERVICE_URL, order-service, ...) and lines that hint at protocols, URLs, brokers and data stores. Substring false positives such as discount for count are rejected.
- Connections. The model decides, from that evidence, which components are connected, in which direction, what flows and over which protocol. It may also add missing databases, queues or external systems it saw evidence for.
Review the result: connections are inferred, not proven. Anything wrong can be fixed in the skill files.
One Markdown file per component in .solution-architecture/skills/:
---
id: api-gateway
name: "API Gateway"
kind: gateway
technology: "Express, TypeScript"
description: "Single entry point that routes web UI requests to backend services."
paths:
- "apps/api-gateway"
connects_to:
- "order-service | order requests | REST"
- "payment-service | payment requests | gRPC"
- "message-broker | order events | AMQP | async"
---
kind: client, frontend, gateway, bff, service, worker, library, database, cache, queue or external. It sets the row, colour and shape.paths: repo-relative folders that implement the component. Leave empty (paths: []) for databases, brokers and external systems. Files are matched to the component with the longest matching path.connects_to: one entry per outgoing link, written target-id | what flows | protocol with an optional fourth async column.layer (optional): force a row, 0 being the top.- The diagram refreshes whenever a skill file changes.
Commands
| Command |
What it does |
Solution Architecture: Open Diagram |
Opens the diagram |
Solution Architecture: Generate with Copilot |
Two-pass generation described above |
Solution Architecture: Generate (Quick Scan, No AI) |
Quick scan without a model |
Solution Architecture: Search Files and Components (Ctrl+Alt+M / Cmd+Alt+M) |
Quick-pick search over files and components |
Solution Architecture: Refresh Diagram |
Reloads files and skills |
Settings
| Setting |
Default |
Description |
solutionArchitecture.excludeGlobs |
node_modules, .git, dist, out, build, ... |
Globs excluded from scanning |
solutionArchitecture.maxFiles |
20000 |
Maximum number of files to index |
solutionArchitecture.modelFamily |
empty |
Preferred Copilot model family |
Privacy
Generate sends the language model you are signed in to (a) a summary of the repo structure and manifests and (b) short single-line excerpts from your code where one component mentions another or where URLs, protocols or data stores appear (roughly 20 KB in total, capped). Nothing is sent unless you run a generate command. Quick scan runs entirely locally.
Development
npm install # also copies Cytoscape into media/
npm run compile
# press F5 in VS Code to launch an Extension Development Host
npm run package # builds a .vsix
Limitations
- Connections are inferred from name mentions, URLs and config, not from a full call-graph analysis. Dynamic service discovery, shared message topics and runtime-only wiring may be missed.
- Large repos: evidence scanning reads up to 250 files per component and 1,200 in total.
- Multi-root workspaces: only the first folder is mapped.
The diagram heading and tab title use your project's own name, taken from the root package.json name, otherwise the folder name. Nothing is hard-coded.
| |
