Analyze a codebase and generate architecture documentation: module responsibilities, dependencies, entry points and run methods.
Install
# from npm (prebuilt)
dsh plugin --profile web add dsh-arch-doc
# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)
dsh plugin --profile web add github:duyanta123/arch-doc
Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).
README
English | 简体中文
A DSH skill plugin: point it at a codebase and it generates architecture documentation (module responsibilities, dependencies, entry points, run methods).
The npm package is named
dsh-arch-doc(the originalarch-docname is blocked by npm's anti-squatting check, renamed 2026-09-02); the GitHub repository and plugin id remainarch-doc. Both refer to the same project.
Positioning
arch-doc is an architecture-documentation plugin: the scanner extracts only hard facts (language, directories, dependencies, entry points — deterministic data), while semantic summaries are added by the LLM following a fixed template, with inferences explicitly marked.
It answers:
- What kind of project is this (language / framework / build system / repo type)?
- How are modules divided, and what is each responsible for?
- How do internal / external dependencies relate?
- Where are the entry points (CLI / Web / Worker / Scheduler / Library)?
- How to install, develop, build, test, run, and deploy it?
Boundaries: scanning is read-only and never executes target-repo code; the scanner has zero dependencies, no subprocesses, and no network access.
Installation
As a DSH plugin (recommended):
dsh plugin --profile web add "github:duyanta123/arch-doc#v0.1.5"
Or from npm:
npm install dsh-arch-doc
Compatibility tiers: the standalone script scripts/arch-profile.mjs runs on Node.js >= 18 (without Node, the runbook falls back to manual shell probing — slightly lower quality, same workflow); as a DSH 0.2.1-rc.2 plugin it is verified with Node.js >= 22.19. Run npm run test:compat to execute an isolated-profile add, dump-config, and startup smoke test.
Local development: add "arch-doc": "file:<local-path>/arch-doc" to the profile's package.json, add "arch-doc" to the bundles array, then restart the profile.
Quick Start
1. Use as a DSH skill
After installing, restart the profile and tell the agent:
Use arch-doc to analyze /path/to/repo
The skill follows its runbook: run the scanner for facts, then generate the document from the template, writing into the target repo's docs/ (see Output).
2. Use as a standalone CLI
node scripts/arch-profile.mjs <repo_path> --probe
node scripts/arch-profile.mjs <repo_path> --scan --max-depth 3
node scripts/arch-profile.mjs <repo_path> --deps
node scripts/arch-profile.mjs <repo_path> --entry
node scripts/arch-profile.mjs <repo_path> --all
CLI Options
| Option | Default | Description |
|---|---|---|
--probe |
- | Detect project type / language / build system, print a summary |
--scan |
- | Directory scan and module partitioning (module responsibility facts) |
--deps |
- | Internal / external dependency extraction |
--entry |
- | Entry point detection (CLI / Web / Worker / Scheduler / Library) |
--all |
- | Run all stages in order, output the full result JSON |
--max-depth <N> |
3 | Directory scan depth (1–10) |
--include-dirs <a,b> |
- | Analyze only these directories (relative to repo_path, comma-separated) |
--exclude-dirs <a,b> |
- | Extra excluded directories (merged with the built-in exclusions covering node_modules, .venv, build artifacts, etc.) |
--language <L> |
auto | Language hint: python / javascript / typescript / go / java / kotlin / generic |
Output
Generates three artifacts in the target repo:
| File | Purpose |
|---|---|
docs/ARCHITECTURE.md |
Structured architecture document (fixed 9+1 chapter skeleton: overview / tech stack / directories / module responsibilities / dependencies / entry points / run methods / key flows / risks / appendix) |
docs/architecture.json |
Machine-readable structured result |
docs/diagrams/module-dependencies.mmd |
Mermaid module dependency graph |
Full sample: examples/sample-output.md —
## 1. Project Overview
- Project name: my-app
- One-line description: sample project (Python FastAPI service)
- Architecture style: layered
- Repository type: monolith
## 2. Tech Stack
- Language: python
- Frameworks: fastapi, uvicorn
- Build/run: docker
Safety Boundaries
- Read-only scanning: the scan phase writes nothing to the target repo's source and never executes target-repo code.
- Zero-dependency runtime: the scanner is a single-file Node script — no third-party dependencies, no subprocesses, no network access.
- Limited output: only three documentation artifacts are written under
docs/. - Safe fallback: without Node, the runbook degrades to manual shell probing and introduces no new dependencies.
Troubleshooting
Mermaid diagrams in the generated ARCHITECTURE.md don't render?
Opening the file directly in a browser over file:// blocks CDN-loaded mermaid.js due to same-origin policy; use a local renderer such as Typora, or paste diagrams/module-dependencies.mmd into mermaid.live. The .mmd source itself is valid.
Large repos scan slowly / output too long?
Start with --max-depth 3, drop to 2 if needed; make sure --exclude-dirs covers node_modules, .venv, and build artifacts.
No entry points detected?
Run --probe first to confirm the project type is right; for mixed-stack repos the primary language's build file wins (e.g. Go+Node → go.mod takes precedence).
Old sessions won't open after upgrading the DSH host to 0.1.5.x? The Session format V3 migration is irreversible and is host behavior; back up session logs before upgrading the host (see the 0.1.4 entry in CHANGELOG.md).
Documentation
- docs/architecture-template.md — the fixed 9+1 chapter skeleton of the output document
- docs/scanning-rules.md — deterministic scanner rules (language detection, repo type, module partitioning, dependency extraction, entry-point classification, run-method extraction)
- examples/ — input and full output samples
- CHANGELOG.md — release notes
- PLUGIN-MAINTENANCE.md — repo maintenance runbook
License
Links
More in this category
tt-a1i/archify#integrations/deepseek-harness★ 96245
Generate validated, self-contained interactive architecture, workflow, sequence, data-flow, and lifecycle diagrams from repositories or system descriptions.
dream-num/dsh-univer-office★ 717
Give DeepSeek Harness a real office environment. Univer Office Plugin brings spreadsheets, docs, slides, canvases, relational tables, and more into one runtime — with connected data, validation, versioned changes, and isolated worktrees for multi-agent collaboration.
Roland0511/dsh-marktext★ 604
WYSIWYG Markdown editor in the DSH right sidebar, built on MarkText's muya engine: open a .md file, edit it as a rendered document, and save back through ctx.fs with a version guard.
ECNU/EduWork#dsh-knowledge-studio★ 354
A workspace-based Studio for source-grounded reports, slides, tables, mind maps, quizzes, flashcards, audio and video, using DSH models and shared artifact services. Office generation requires Python 3.12+ with its dependencies and DSH_OFFICE_PYTHON configured; media rendering requires Chromium, and local ASR additionally requires whisper.cpp and a model.
PerryLink/dsh-industry-research★ 219
Deterministic industry research reports for DeepSeek Harness — company and industry research flows produce structured, verifiable reports from staged evidence.
joeseesun/qiaomu-ui-learn-dsh★ 84
Browse UI design references and interaction examples, take design quizzes, and export learning notes as Markdown.
Community comments
Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.