SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsnan-codebase-architecture-atlas

nan-codebase-architecture-atlas

Coding & development

View repository

Updated 10-16 01:34

About this skill

Codebase Architecture Atlas

Codebase → ontology (entities / relationships / data flows / design principles) → drillable interactive architecture web page.

Deliverables

designs/<slug>-architecture-atlas/:

  • Multi-file project:<Name> Atlas.html + data.js(ontology data) + app.js(rendering engine)
  • Single-file offline HTML: double-click to open, directly distributable
  • Four levels of depth: L1 panorama overview → L2 module-level topology → L3 module internals ×N → L4 data flow sequence diagrams; plus a design principles page
  • Interaction: single-click a component to see the details drawer (responsibilities/relationships/key files/deployment/notes), double-click to drill down, ⌘K global search, pan and zoom, URL hash positioning, top-bar theme switching (light/dark/paper/sepia)

Three key insights

  1. The rendering engine is ready, do not rewrite the frontend。assets/template/ The engine reads the global ATLAS object; all of your creation is data.js(ontology) + view coordinates. The engine only binds "form primitives" (11 forms such as black background/dashed box/monospace font, and 4 line types), and does not bind any specific kind.
  2. The ontology relies on exploration, not imagination—including the vocabulary itself. Every entity/relationship must have code evidence (file path, class name, protocol name); anything uncertain goes into the entity notes, fabricating is forbidden. The kinds/relKinds vocabulary must likewise be derived from the exploration report: not every codebase has daemons or user processes, and the legend is automatically generated based on the kinds actually used. Pitfalls and debt are the most informative parts of the ontology; model them faithfully.
  3. Layout is design, not algorithm. Arrange coordinates by hand; the pipeline only goes in one direction (left→right or top→bottom); the appearance of long diagonal lines = a signal to rearrange.

Workflow (five stages, executed in order)

0. Theme (optional, decided once before generation)

If the user specifies a theme (e.g. "use a dark theme"), follow it; if unspecified, you may default to light, or proactively ask for a preference. Write the determined theme into data.js 's meta.theme(light/dark/paper/sepia); the generated diagram defaults to that theme; viewers can still switch in the top bar, or specify it via the URL ?theme=<name> . The theme only remaps visual tokens and does not change form semantics (see references/visual-and-layout.md §6)。

1. Parallel exploration

  • Split into 4–8 exploration units by "repository / high-cohesion module / cross-boundary interface", with parallel sub-agents (thorough level). The most important modules each occupy a unit on their own; cross-repo/cross-process/cross-language boundaries (IPC/FFI/protocol) must have someone specifically responsible. Splitting follows high-cohesion aggregation, not mechanical splitting by directory—monorepos by bounded context, giant repos split the core brain, execution limbs, and entry shell apart; small repos (single crate / single package / <20 top-level files) need only 1–2 units, no need to pad the count. For splitting guidelines by tech stack and scale calibration (expected depth of entities/relationships/views/data flows/principles), see references/ontology-modeling.md §1。
  • Depth floor (to prevent "shallow exploration"): In each unit's instructions, state "entities ≥15, relationships ≥12, data flows ≥3", and enforce the "VI. Corrections and Course Adjustments" section—the sub-agent's corrections to task assumptions (e.g. "X is actually not Y") are the highest-value intelligence; missing them means distortion.
  • Each sub-agent returns a six-part report: entity list, relation list, core data flow, deployment form, architecture details and pitfalls, and corrections and adjustments.
  • When there are ≥5 units, have the sub-agents write their reports to designs/<slug>-architecture-atlas/exploration/*.md and then read them one by one—aggregated returns exceeding the single-result limit will be truncated, and writing to disk also makes review easier.
  • The reports on disk are authoritative: sub-agents write to disk earlier than the batch completion receipt, and the receipt may arrive late or even after delivery. Once you have read all of exploration/*.md , you can model; do not wait for the receipt, and do not redo the work just because the receipt is late.
  • Do fact-checking before modeling: for each report's "corrections and adjustments" items, pick the 2–4 most critical claims and verify them with grep in the repository (bidirectional semantics, data flow direction, deprecation status), and write the verification conclusions into the entity notes or principles.
  • Instruction template (apply directly):references/ontology-modeling.md §1。

2. Ontology modeling

  1. Toolchain pre-check (once, before modeling):bash <skill>/scripts/preflight.sh <dir>—report early whatever is missing among node/python3/PIL/Chrome; don't wait until screenshots to find out. Also node validate_atlas_data.js <dir>/data.js run the template once to confirm the toolchain baseline.
  2. cp -r <skill>/assets/template designs/<slug>-architecture-atlas/(when flattening, do not mv overwrite files with the same name, see the hard rules).
  3. cp data.js data.js.bak leave a fallback, then start modifying.
  4. Push the vocabulary first: from the exploration reports, summarize the entity/relation kinds that actually exist in this project, and rewrite data.js 's kinds/relKinds—prune zombie kinds in the default vocabulary that don't match, change labels according to the domain language, and add kinds as needed (just pick one form; no need to change the engine). Derivation method:references/ontology-modeling.md §2。
  5. Then fill in the data: entities/relations/views/flows/principles are all filled in by dynamic inference from exploration. Field-level schema and modeling rules:references/ontology-modeling.md §3–4; complete examples (for learning only):assets/template/data.example.js. Compare deeply against the scale calibration table; if you don't reach the lower bound, keep digging through the exploration reports.
  6. Correction-type claims go into the ontology: after reading each report, grep data.js once for the key facts in the "corrections and adjustments" items—anything not in the ontology must either be added as an entity/relation or written into the notes of the relevant entity; modeling it as an old assumption is forbidden.
  7. Iron rule: an entity must have a home view; both ends of a relation must exist; similar small entities are merged into "family" nodes, and merging is preferred over fragmentation;ids may only contain letters/digits/_/-(view ids go into the URL hash, entity ids are concatenated into edge keys).When ids are used as object keys, always quote them—keys containing - ("exec-server": {...}) with missing quotes = JS syntax error, and validate reports PARSE FAIL and the whole file cannot be parsed; for ids, prefer _ over -。

3. View layout

  • The number of views follows the scale calibration (see references/ontology-modeling.md §1): small repositories start with 4 views, medium 5–6, large 7–8. Each L2 domain must have at least 1 L3 drill-down view (if the domain has ≥8 entities, it must be split); data flow sequence diagrams are configured as "at least 1 per L2 domain + at least 1 end-to-end cross-domain flow".
  • Each view has ≤22 nodes; draw group boxes (group) first, then arrange node coordinates.Arrange the first layout according to the lint geometry model: normal nodes 208×70, large nodes 250×86; horizontal center distance ≥260, vertical ≥130; lint判定 = Bezier t∈[0.1,0.9] sampled in steps of 0.04, node box inset by 8px for hit判定, label midpoint distance <18px for mutual overlap (parameters see references/visual-and-layout.md §4 end). With this initial arrangement, the correction rounds can be reduced to 2–4 rounds.
  • Rules and visual semantics:references/visual-and-layout.md。

4. Validation (deliver only when all green)

node <skill>/scripts/validate_atlas_data.js <dir>/data.js   # 引用完整性,须输出 0 BAD;解析错误带 文件:行号
node <skill>/scripts/lint_atlas_layout.js <dir>/data.js     # 布局几何:重叠/越界/边穿节点/标签互叠/图例死区
bash <skill>/scripts/shoot_atlas.sh <dir> 4311 overview,endpoint,srv   # 逐视图截图(需本机 Chrome)
  • Validate first, then lint, and finally screenshot: lint can list most geometry problems as a checklist before screenshotting, compressing "screenshot—visual inspection—coordinate fixes" to 1–2 rounds; go through lint's WARNs one by one, confirm there are no safety issues, and only then proceed to screenshot.
  • When a port is occupied by another server, the shoot script will automatically probe the next free port and print the port actually used—pay attention to the "提示: 端口 ... 改用 ..." in the output. The newly started server will be recorded in <dir>/.atlas-server.pid, to clean up use shoot_atlas.sh <dir> --stop。
  • When the legend panel blocks a node in the lower-left corner, use NOLEGEND=1 bash shoot_atlas.sh ... to collapse the legend and then screenshot (the engine supports #/view?legend=0)。
  • If the screenshot shows "Error response / 404": it means the server root directory on the port is incorrect; manually confirm http://localhost:<port>/<dir名>/ is reachable and then re-screenshot.When starting the server manually, pay attention to the URL form:python3 -m http.server <port> The root directory is the current directory, and the URL is /Atlas.html(no directory prefix), which differs from the shoot script's /<dir名>/ prefix—first curl to confirm the actual path and then screenshot.
  • DOM verification without a visual environment: Chrome --dump-dom must include --virtual-time-budget=12000 and other JS execution time parameters; otherwise it returns a few-hundred-byte empty shell (the engine has not rendered). The engine prerenders all views into the same SVG, so it is normal for each view's dump size to be the same—a single dump is enough to grep all view names + key entity names in full. Use PIL for ink coverage (pip3 install pillow install it if missing); the normal range is 2–9%.
  • When you need to precisely recheck a certain edge/coordinate, use a node probe:cp data.js /tmp/probe.js && echo "module.exports = ATLAS;" >> /tmp/probe.js then node -e require and calculate by hand according to the formula in §4——do not strip comments with regex and then eval(the sessions/*.jsonl in the string will be /*…*/ accidentally damaged; this pitfall was hit in actual testing).

Read the images one by one for visual inspection: node overlap / isolated nodes / label occlusion (including overlapping edge labels) / incorrect group-box containment / black background with no text / legend dead zones → fix → re-screenshot. Visual inspection checklist:references/visual-and-layout.md §3。"should be fine" is not allowed. If there is no visual model, perform equivalent verification according to references/visual-and-layout.md §5, and declare "not visually inspected by a human" in the delivery notes.

5. Delivery

python3 <skill>/scripts/build_standalone.py <dir> "<入口文件名>.html"
rm <dir>/data.example.js          # 模板示例,勿带入交付

Report to the user: HTTP access URL, single-file path, ontology statistics (number of entities/relations/data flows), known limitations (such as long cross-group edges).

The source project is the only editing entry point: if the user requests keeping only the single-file version, first inform them that "after deleting the source, modifying the diagram requires reverse unpacking"; if the source has been deleted and the single-file version has not been manually modified, you can use scripts/extract_standalone.py to restore the source project (round-trip byte-conservation verification; after restoration, validate first and then rebuild).

Hard rules

  • Explore first, then model—large diagrams that skip exploration are bound to be distorted; the exploration report only needs conclusions and paths, not source code dumps.
  • The vocabulary (kinds/relKinds) is data, not protocol—it must be derived from this project's exploration; delivering zombie types with a default vocabulary is prohibited; form primitives (form/line type) are the protocol; when adding a new kind, choose form and do not modify the engine.
  • data.js Run validate immediately after every change; before changes first cp data.js data.js.bak;Do not perform destructive replacements with fuzzy regex on data files—rewrite in sections, or restore from backup.
  • ids used as object keys must be quoted; entity/view ids should preferably use _ instead of -(hyphenated keys missing quotes = validate PARSE FAIL).
  • Before modeling, run scripts/preflight.sh to precheck the toolchain—missing Chrome/PIL should be discovered at the modeling stage, not delayed until shoot reports it.
  • When the template directory is flattened (put template/ Atlas.html/app.js/data.js into the project root)Prohibited mv overwriting files with the same name——mv template/data.js . will silently overwrite already-written ontology data; first cp or confirm the target does not exist.
  • Screenshots must be visually inspected one by one; fix each issue found, and after fixing, retake the same view to confirm.
  • The single-file version is generated only by build_standalone.py , and after generation it is not hand-edited; to make changes, edit the source files and regenerate.
  • Visually, by default follow the template's built-in OpenAI-style monochrome system (white background, hairline rules, black background = highest-privilege entity); the built-in light/dark/paper/sepia four themes are overridden via CSS tokens, switching does not change the form semantics, adding a new theme only adds a token block without changing the engine, and do not introduce color or gradients.