AppDoc provides automated documentation extraction, quality assessment, and improvement tools for codebases. The toolkit is implemented in PowerShell and outputs comprehensive reports and recommendations based on analysis of your codebase and generated documentation.
Note: The current workflow is local-first. Deterministic scripts generate technical artifacts, and readability enhancements are performed directly in your IDE chat session.
- PowerShell 7+ (required for all scripts)
- Windows OS (tested)
- VS Code + GitHub Copilot Chat (for
/appdoc.begin,/appdoc.enhance,/appdoc.diagramscommands) - Target codebase path where
docs/output can be written
Primary deterministic workflow:
.appdoc/scripts/powershell/run-all-generators.ps1— end-to-end deterministic pipeline.appdoc/scripts/powershell/run-appdoc-enrich.ps1— bootstrap + semantic apply + enrichment gate orchestration.appdoc/scripts/powershell/run-appdoc-semantic-enrich.ps1— file-driven semantic input/output apply for enriched evidence.appdoc/scripts/powershell/ci-enrichment-gate.ps1— enrichment quality gate (Phase 2.5 checks).appdoc/scripts/powershell/appdoc.diagnose.ps1— environment/readiness diagnostics.appdoc/scripts/powershell/validate-documentation.ps1— structured validation + scoring.appdoc/scripts/powershell/remediate-generated-docs.ps1— post-generation cleanup + evidence traceability
Key generators in current workflow include:
generate-overview.ps1,generate-start-here.ps1,generate-docs-index.ps1generate-api-inventory.ps1,generate-data-model.ps1,generate-config-catalog.ps1generate-build-cookbook.ps1,generate-test-catalog.ps1,generate-task-guides.ps1generate-debt-register.ps1,generate-dependencies-catalog.ps1generate-c4-mermaid-diagrams.ps1
- Download or clone the
AppDocrepo into the root of the codebase you want documented. - Open that repository in Visual Studio Code.
- Recommended: Generate workspace instructions or run an INIT command to have your AI investigate your codebase.
- Open the GitHub Copilot Chat and run
/appdoc.beginto start the guided AppDoc workflow. - Run
pwsh ./.appdoc/scripts/powershell/run-appdoc-enrich.ps1 -RootPath <codebase-path>to bootstrap evidence, apply semantic enrichment, and validate gate checks. - Run
/appdoc.enhanceto apply editorial polish after enrichment.
That's it — AppDoc will perform environment checks and walk you through analysis and generation.
AppDoc now generates Mermaid C4 diagrams in Markdown format under docs/diagrams/.
docs/diagrams/c4-context.mddocs/diagrams/c4-container.mddocs/diagrams/internal-flow.mddocs/diagrams/data-flow.mddocs/diagrams/critical-sequences.mddocs/diagrams/data-lineage-core.md(plus partition files when needed)docs/diagrams/index.md
Use /appdoc.diagrams to AI-enhance those Mermaid diagrams in place.
You can run deterministic generation directly with:
pwsh ./.appdoc/scripts/powershell/run-all-generators.ps1 -RootPath <codebase-path>
Useful flags:
-DryRun— previews which scripts and phases would run without generating artifacts.-StrictValidation— fails the run when generated artifacts score below threshold.-QualityThreshold <1-100>— sets strict validation cutoff (default:80).-SkipDiagrams— skips C4 diagram generation. Readability and narrative enhancements are handled directly in your IDE/chat AI session over local workspace context and generated evidence artifacts.
Enrichment bootstrap command:
pwsh ./.appdoc/scripts/powershell/run-appdoc-enrich.ps1 -RootPath <codebase-path>
Strict gate mode (fails when enrichment checks do not pass):
pwsh ./.appdoc/scripts/powershell/run-appdoc-enrich.ps1 -RootPath <codebase-path> -StrictGate
By default, semantic apply runs before the gate and writes:
docs/evidence/semantic/input/*.semantic.input.json(records requiring semantic values)docs/evidence/semantic/output/*.semantic.output.json(optional external semantic responses)docs/evidence/semantic/applied/*.semantic.applied.json(post-apply snapshots)
Use -SkipSemanticApply only when you intentionally want to gate existing enriched files as-is.
Run gate standalone:
pwsh ./.appdoc/scripts/powershell/ci-enrichment-gate.ps1 -RootPath <codebase-path>
Recommended sequence:
run-all-generators.ps1run-appdoc-enrich.ps1/appdoc.enhance
Mermaid C4 diagrams can be generated directly with:
pwsh ./.appdoc/scripts/powershell/generate-c4-mermaid-diagrams.ps1 -RootPath <codebase-path> -OutputPath <codebase-path>/docs -DiagramLevels All
To AI-enhance generated Mermaid diagrams in place, run /appdoc.diagrams in Copilot Chat.
Diagnostics and validation commands:
pwsh ./.appdoc/scripts/powershell/appdoc.diagnose.ps1 -RootPath <codebase-path> -Fixpwsh ./.appdoc/scripts/powershell/validate-documentation.ps1 -RootPath <codebase-path>pwsh ./.appdoc/scripts/powershell/validate-documentation.ps1 -RootPath <codebase-path> -Strict -Threshold 80
Last updated: 2026-02-17
| Status | Language | Framework | Version Range | Coverage | Notes |
|---|---|---|---|---|---|
| ✅ Full | C# | ASP.NET Core | 2.1+ | 90% | Controller/route detection, config extraction, model heuristics |
| C# | ASP.NET MVC 5 | 5.x | 75% | Action detection supported; some attribute edge cases remain | |
| JS/TS | Express.js | 4.x | 60% | Basic app.METHOD and router patterns; middleware chains limited |
|
| Python | Flask | 2.x+ | 65% | @app.route and common blueprint patterns supported |
|
| Python | FastAPI | 0.9+ | 70% | Decorator and response model heuristics supported | |
| Python | Django | 3.x+ | 55% | URL pattern extraction supported; deep viewset inference limited | |
| Java | Spring Boot | 2.x+ | 60% | @*Mapping and @RequestMapping scanning supported |
| Status | Framework | Planned |
|---|---|---|
| ❌ Not supported | Ruby on Rails | Planned (TBD) |
| ❌ Not supported | Go (Gin/Echo) | Planned (TBD) |
| ❌ Not supported | PHP (Laravel) | Planned (TBD) |
- C#:
*.csproj,*.sln,[ApiController],[HttpGet],MapControllers - JS/TS:
package.jsondependencies (express) andapp.get/router.getpatterns - Python:
requirements.txt/pyproject.tomldeps (flask,fastapi,django), route decorators,urls.py - Java:
pom.xmlSpring dependencies,@RestController,@RequestMapping
Open an issue with:
- Framework name and target version
- Minimal sample project or repo
- Expected artifacts (API inventory, data model, config catalog, etc.)
- Known route/config/model patterns used in your codebase
- Start Here - Role-based onboarding and quick orientation
- Overview - High-level system summary and documentation index
- API Inventory - HTTP endpoints and API contracts
- Data Model - Data structures and entities
- Configuration Catalog - Configuration options and environment variables
- Build Cookbook - Build and deployment commands
- Test Catalog - Test suites and coverage
- Task Guides - Task-centric implementation and operations playbooks
- Tech Debt Register - Known issues and improvement opportunities
- Dependencies Catalog - External packages and libraries
- Documentation Index - Landing page linking all generated artifacts
- C4 Context Diagram - Mermaid C4 system context
- C4 Container Diagram - Mermaid C4 container view
- Internal Flow Diagram - Request-to-processing runtime flow
- Data Flow Diagram - Input/transform/output data movement
- Critical Sequences - High-signal end-to-end request journeys
- Data Lineage Core - Partitioned lineage view for readability
- Diagram Index - Guided architecture reading order
- Quality Report - Generator quality scoring output
- Validation Report - Deterministic validation metrics
- Diagnostics Report - Environment/runtime diagnostics
- Evidence Manifest - Traceability index for artifact evidence records
- Ensure all required scripts and modules are present in
.appdoc/scripts/powershell/ - Use PowerShell 7+ for compatibility
- Check file paths for documentation output
- Review error messages for missing files or permissions
- Run
pwsh ./.appdoc/scripts/powershell/appdoc.diagnose.ps1 -RootPath <codebase-path> -Fixto validate environment and script readiness
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
License file is not currently included in this repository. Add a LICENSE file before external distribution.
For support, please open an issue on GitHub.