Introduction and Goals

docToolchain is an open-source implementation of the docs-as-code approach for software architecture documentation. It processes AsciiDoc source files and generates documentation in multiple output formats (HTML, PDF, DocBook, Reveal.js slides, microsites). Beyond format conversion, docToolchain integrates with external systems — Atlassian Confluence and Jira, Enterprise Architect, Structurizr, Excel, PowerPoint, and Visio — to import data into documentation or publish documentation to collaboration platforms.

v4 represents a fundamental shift: from a Gradle-based build tool to a lightweight, LLM-native docs-as-code platform. Gradle is removed entirely (ADR-3), the core/ compilation module is dissolved back into scripts, jBake is replaced by a custom Groovy-based site generator (ADR-4), and the strategic focus shifts to LLM integration via MCP, Skills, Prompts, and Semantic Anchors (ADR-5).

Requirements Overview

The core functional requirements are:

  • Document generation: Convert AsciiDoc sources with embedded PlantUML diagrams to HTML, PDF, DocBook, and Reveal.js slides

  • Microsite generation: Build complete static documentation websites with a modern UI, using a custom Groovy-based generator (replacing jBake)

  • Confluence publishing: Publish generated HTML pages to Atlassian Confluence, maintaining page hierarchies, attachments, and labels

  • Jira integration: Export Jira issues and sprint changelogs to AsciiDoc or Excel format for inclusion in documentation

  • External tool import: Extract diagrams from Enterprise Architect, Structurizr, Visio, and PowerPoint; import tables from Excel; convert Markdown to AsciiDoc

  • Git metadata extraction: Generate changelogs and contributor lists from Git history

  • Cross-platform CLI: Provide a single command-line interface (dtcw) that works on Linux, macOS (including Apple Silicon), and Windows. v4 scope: Linux and macOS run natively; Windows is supported via WSL2 in v4 — the native dtcw.ps1/dtcw.bat v4 execution path is not yet implemented (Chapter 11 debt).

  • Multiple execution environments: Support local installation, Docker containers, and SDKMAN-based installation

  • Zero-configuration start: Enable first-time users to generate documentation with minimal setup

  • LLM-native document access: Provide structured document navigation and modification via MCP server (daCLI), supporting Skills, Prompts, and Semantic Anchors

  • Fast execution: Minimal startup overhead — no build framework initialization, no daemon, no dependency resolution at runtime

Quality Goals

These are the top five quality goals that drive the architecture decisions in this document. Further quality characteristics (LLM friendliness, LLM-managed configuration, modern UI, v3 backward compatibility, script-first maintainability, minimal repository footprint, clean uninstallation) are elaborated as derived requirements in the Chapter 10 quality tree, each cross-linked to its quality scenario.

Priority Quality Goal Scenario

1

No implicit cloud processing

No data leaves the user’s machine unless explicitly configured. External services (kroki.io, Confluence, Jira) trigger a warning. Default diagram rendering is local via Docker. (QS-16)

2

Performance (Startup + Throughput)

Startup under 3 seconds, 50-page HTML generation under 10 seconds. No Gradle daemon, no dependency resolution overhead. (QS-9)

3

Cross-platform portability

Identical output on Linux, macOS (including Apple Silicon), and Windows across local, Docker, and SDKMAN environments. In v4, Windows is covered via WSL2; a native Windows wrapper path is planned (Chapter 11 debt). (QS-2, QS-10)

4

Actionable error guidance

When something fails, docToolchain tells the user what to do — not what went wrong. Every error message is a concrete action: which file to close, which config to set, which command to run. (QS-17)

5

Ease of adoption

A developer generates HTML documentation in under 5 minutes using only dtcw, including automatic Java and docToolchain installation. (QS-3, QS-6)

Stakeholders

Role/Name Contact Expectations

Documentation Author

Technical writers and developers writing docs

Simple CLI to generate and preview documentation. Seamless integration with editors, version control, and LLM assistants.

LLM Agent

AI assistants (Claude, ChatGPT, etc.) via daCLI MCP server

Structured document access, section-level read/write, search, validation. Machine-readable Semantic Anchors for reliable navigation.

Contributor / Developer

Open-source contributors extending docToolchain

Script-first architecture — no compilation step, no build system knowledge required. Fast feedback loop. Clear, simple codebase.

DevOps Engineer

CI/CD pipeline maintainers

Headless execution mode, Docker support, predictable exit codes. Fast builds without Gradle overhead.

Project Maintainer

Ralf D. Mueller and core team

Sustainable, lightweight architecture. No dependency on unmaintained upstream projects (Gradle plugins, jBake). Full control over the stack.

End User

Readers of generated documentation

Modern, accessible UI in HTML and PDF. Responsive microsites with dark mode, search, and clear navigation.