duyanta123/arch-doc

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 original arch-doc name is blocked by npm's anti-squatting check, renamed 2026-09-02); the GitHub repository and plugin id remain arch-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.4"

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.1.5-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 / 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

MIT