|
1 | 1 | # /devlens architecture — system design brief |
2 | 2 |
|
3 | | -Produce a high-level map of the codebase. Arguments: none (operates on the cwd graph; `-g <id>` to target another). |
| 3 | +Produce a **complete** map of the codebase, not a sample. The graph can be large (hundreds of nodes); cover every node type, the module/layer structure, the key connections **and their edge types**, and the risks. Arguments: none (operates on the cwd graph; `-g <id>` to target another). |
4 | 4 |
|
5 | 5 | **Needs summaries** for the richest output — follow the freshness/summarize-permission policy in SKILL.md first. |
6 | 6 |
|
7 | | -## Commands used |
8 | | -1. `devlens overview --json` — fingerprint: `framework`, `router`, `stateManagement`, `dataFetching`, `databases`, `rawDependencies`, stats, central nodes. |
9 | | -2. `devlens top-nodes -l 15 --json` — the most central modules (`-l` sets how many). |
10 | | -3. `devlens subgraph <seedNodeId> --json` — run on the top 2–3 central node ids from step 2 to reveal their clusters. |
11 | | -4. `devlens cycles --json` — circular dependency groups (`{total, cycles}`). |
| 7 | +## Commands & how to use them |
| 8 | +1. **Headline stats:** `devlens overview --json` → `stats.totalNodes`/`totalEdges`, `routeCount`, `fingerprint` (framework, router, stateManagement, dataFetching, databases), plus `topNodes` (10) and `topFiles` (10). |
| 9 | +2. **Full node inventory (this is what makes it complete):** `devlens find-nodes -l 2000 --json` → **all** nodes as compact refs `{id, name, type, filePath, score, severity, summary}`. From this, compute: |
| 10 | + - the **node-type distribution** (counts per type: COMPONENT, FUNCTION, FILE, ROUTE, STATE_STORE, HOOK, …); |
| 11 | + - **modules/layers** by grouping nodes on their top-level directory (e.g. `src/app/api`, `src/components`, `src/app/firebase`, `src/components/ZustandStores`). |
| 12 | +3. **Backbone enumeration** (the structural anchors): |
| 13 | + - Entry points: `devlens find-nodes -t ROUTE -l 200 --json`. |
| 14 | + - State: `devlens find-nodes -t STATE_STORE -l 50 --json`. |
| 15 | + - Key UI/logic: the highest-`score` COMPONENT/FUNCTION nodes from the inventory (or `devlens top-nodes -l 20 --json`). |
| 16 | +4. **Connections + edge types** — do **NOT** use `devlens subgraph --json` (it currently prints a text cluster listing, not JSON). Instead, for the central nodes (topNodes) and each store/route hub: |
| 17 | + - `devlens khop <id> -r 2 --json` (downstream) and/or `devlens blast-radius <id> -r 2 --json` (upstream). Each returned node carries **`viaEdge`** (the edge type: CALLS, IMPORTS, READS_FROM, WRITES_TO, PROP_PASS, USES, HANDLES, …) and `hop`. |
| 18 | + - For one node's immediate wiring: `devlens get-node <id> --json` → `callers`/`callees`, each with `viaEdge`. |
| 19 | + - Aggregate the `viaEdge` values to describe how modules connect and which edge types dominate. |
| 20 | +5. **Meaning (batch, cheap):** `devlens get-summaries <id...> -i business --json` (functional) **and** `-i technical --json` for the backbone nodes. Use the **functional** summary to say what each module/node means for the product and the **technical** summary to say what it does — describe every module and backbone node from its summaries, not from its name alone. |
| 21 | +6. **Security posture:** every compact node ref carries a `severity` (none|low|medium|high); also run `devlens security --min-severity low --json` for the flagged set with `securitySummary`. Fold this into the brief — call out which modules/nodes carry medium/high risk. |
12 | 22 |
|
13 | | -## Output |
14 | | -A concise brief: |
| 23 | +## Output — a thorough brief |
15 | 24 | - **Stack** — framework + router, state management, data fetching, databases, notable deps. |
16 | | -- **Shape** — node/edge counts, dominant node types. |
17 | | -- **Core modules** — the central nodes (name, file, one-line role from their summary). |
18 | | -- **Clusters** — the cohesive groups from subgraph, and how they relate. |
19 | | -- **Risks** — any cycles, and unusually high-fan-out hubs. |
| 25 | +- **By the numbers** — `totalNodes`/`totalEdges`, `routeCount`, and the **node-type distribution** (counts per type). |
| 26 | +- **Modules / layers** — the directory groups, each with its purpose **drawn from the functional + technical summaries** and representative nodes. |
| 27 | +- **Backbone** — key routes (entry points), stores (state), and central components/functions, each with a one-line role from its summary. |
| 28 | +- **How it connects** — the dominant **edge types** (CALLS/IMPORTS/READS_FROM/WRITES_TO/PROP_PASS/HANDLES/USES/…) and the main data/control-flow paths between modules (from the `viaEdge` data in step 4). |
| 29 | +- **Security posture** — modules/nodes with medium/high `severity`, summarized from their `securitySummary` (step 6). |
| 30 | +- **Risks** — cycles (`devlens cycles --json`) and high-fan-in hubs (large blast radius). |
20 | 31 |
|
21 | 32 | End by offering `/devlens diagram architecture` for a visual and `/devlens explain` for an onboarding walkthrough. |
0 commit comments