Large Language Models (LLMs) face significant challenges when interacting with extensive documentation projects. The primary issues are:

dacli (Documentation Access CLI) aims to solve these problems by providing structured, content-aware tools for interacting with AsciiDoc and Markdown projects. Available as both a CLI tool and MCP server, it enables efficient navigation, reading, and modification of complex documentation.

The architecture will prioritize the following key quality goals, derived from the non-functional requirements:

The primary stakeholders of dacli are:

The system must adhere to the following technical constraints, derived directly from the PRD:

To ensure consistency and quality, the following conventions will be followed:

From a business perspective, dacli acts as a specialized middleware that enables technical users to interact with documentation projects more effectively. It abstracts away the complexity of file-based document structures and provides both a CLI for direct use and an MCP server for LLM integration.

On a technical level, the MCP server is spawned as a subprocess by an MCP-compliant client and communicates via stdio (standard input/output). The CLI tool can be invoked directly from the shell. Both interfaces interact directly with the file system to read documentation source files and write back modifications.

The core of the architecture is a dual approach:

To implement this strategy, the following technology stack is proposed. The choices are guided by the need for strong text processing capabilities, a robust ecosystem, and fast development.

The project uses uv for Python environment and dependency management:

The pyproject.toml defines all dependencies, and uv.lock ensures reproducible builds across all environments.

The architectural strategy directly addresses the top quality goals defined in Chapter 10.

The dacli system provides two interfaces: a CLI tool for direct command-line usage and an MCP server for LLM integration. The file system serves as the system’s database (see ADR-001).

We now zoom into the MCP Server container. It is composed of several components, each with a distinct responsibility.

The CLI tool (dacli) provides the same documentation operations as the MCP Server, accessible via command-line. It shares the core components (parsers, index, file handler) and adds a presentation layer for terminal output.

Both the MCP Server and CLI containers use the same "Document Parsers" component. Internally, it contains two independent parser implementations with distinct architectures, sharing utility functions via parser_utils.

Key classes:

For the internal structure of each parser (Level 4: Code), see the component specifications:

The following table maps components to the MCP tools:

The following core data models are used across components (see API Specification for details):

This is the most common read operation. A client requests the content of a specific section using its hierarchical path.

This scenario shows the critical write operation. The process must be atomic to ensure data integrity, as required by quality goal REL-1. This is achieved by writing to a temporary file first.

When the server starts, it needs to parse the entire documentation project to build an in-memory index of the structure. This enables fast lookups for subsequent requests.

The application is designed to be lightweight and self-contained, in line with its constraints (no external services). Two deployment strategies are supported:

For production use, dacli runs as a subprocess managed by the MCP client. The typical deployment involves:

Security is addressed through standard, well-understood mechanisms.

The error handling strategy is designed to be robust and developer-friendly, supporting the quality goals of Reliability and Usability.

Status: Accepted (2025-09-18)

Context: The PRD requires that the system integrates with existing Git workflows, that files remain human-readable, and that there are no database dependencies. We need a simple, robust way to store the documentation content that honors these constraints.

Decision: The file system will be treated as the single source of truth. The server will not have its own persistent state. All content and structure information is derived directly from the .adoc and .md files within the project directory.

Consequences:

Status: Accepted (2025-09-18)

Context: The quality goal PERF-1 requires API calls to respond in under 2 seconds. Reading and parsing text files from disk on every request would be too slow for large projects, as identified in the runtime analysis.

Decision: On startup, the server will perform a one-time scan of the entire project directory. It will parse all documentation files and build an "In-Memory Structure Index". This index will hold metadata about each document, including section names, hierarchical paths, and the start/end line numbers for each section in its source file. Read requests will consult this index to find the exact byte range to read from a file.

Consequences:

Status: Accepted (2025-09-18)

Context: A programming language and web framework are needed to build the MCP API Server. The choice must align with the need for rapid development, strong text-processing capabilities, and high performance for an I/O-bound application.

Decision: The backend will be implemented in Python. The FastAPI framework will be used to build the web server and API endpoints.

Consequences:

Status: Accepted (2025-09-18)

Context: The quality goal REL-1 (Atomic Writes) is critical to prevent file corruption during update operations. A failure (e.g., disk full, application crash) during a file write could leave a document in an unrecoverable, partially-written state.

Decision: The File System Handler component will implement atomic writes using a backup-and-replace strategy:

Consequences:

Status: Accepted (2025-09-18)

Context: A core feature is the ability to map a hierarchical path (e.g., chapter-1.section-2) to a precise location in a source file. This is complicated by AsciiDoc’s include::[] directive, as content from multiple files is logically part of one document. Existing parsers often flatten the document, losing this critical source-map information.

Decision: A custom document parser will be developed. This parser will be responsible for:

Consequences:

Status: Accepted (2026-01-20)

Context: Python projects require dependency management for reproducible builds. Traditional tools like pip, pipenv, and poetry have limitations in speed, reliability, or lock file handling. The project needs fast dependency resolution for efficient CI/CD and a deterministic lock file for reproducible deployments.

Decision: Use uv (https://github.com/astral-sh/uv) as the Python package manager and virtual environment tool. All dependencies are defined in pyproject.toml and locked in uv.lock.

Consequences:

Status: Accepted (2026-01-20)

Context: The core data models (SourceLocation, Section, Element, CrossReference, Document) need to be defined for the parser and API layers. These models must be serializable to JSON for API responses and should be type-safe. Two main options exist in the Python ecosystem: Python’s built-in dataclasses module and the third-party pydantic library.

Decision: Use Python’s built-in dataclasses for all core data models. JSON serialization will be achieved using dataclasses.asdict() combined with custom serialization for Path objects.

Consequences:

Status: Accepted (2026-01-22)

Context: The current path generation creates section paths based solely on heading titles (slugified). This works well within a single document, but when multiple documents are indexed together, sections with identical titles receive identical paths. This causes:

Example: Both guides/installation.adoc and guides/advanced.adoc have a section == Prerequisites, resulting in path collision at prerequisites.

Issue #123 (now fixed) addressed within-document duplicates by appending -2, -3 suffixes. This ADR addresses the cross-document case.

Note: Backwards compatibility is not a requirement for this decision.

Decision: We will implement Option A: File Prefix in Path as the solution.

Section paths will include the relative file path (without extension) as a prefix, separated by a colon:

For root sections (document titles), the path will be the file path alone:

Consequences:

Positive:

Negative:

Status: Accepted (2026-02-07)

Context: Issue #186 proposed adding an experimental dacli ask "question" command that uses an LLM to answer questions about the documentation. The idea was to iterate through all documentation files, pass each file’s content together with the question and accumulated findings to an LLM, and consolidate the results into a final answer.

Several approaches were evaluated during implementation:

The fundamental insight: dacli is designed to be used by LLMs (both via MCP and CLI). The calling LLM can already:

The ask command is therefore redundant — it implements a slower, less capable version of what the calling LLM already does natively.

Decision: We will not implement a built-in LLM-based ask feature. Instead, we rely on the calling LLM to use dacli’s existing navigation and content access tools to answer questions.

A future RAG-based approach (Retrieval-Augmented Generation) could be considered as a separate feature. RAG would use vector embeddings for fast similarity search and only require a single LLM call for the final answer. This would be significantly faster but would not cover the entire documentation (only the top-k matching chunks).

Consequences:

Positive:

Negative:

Status: Accepted (2026-02-07)

Context: The original architecture documents (Quality Requirements, Concepts) assumed a Web UI component for dacli — specifically a document structure visualization (#12) and a real-time diff display (#13). Quality scenario USAB-3 described a "web UI" showing red/green diffs after modifications.

However, dacli has evolved into a pure CLI tool and MCP server designed for LLM integration. The primary consumers are:

A Web UI would be a fundamentally different product — it requires frontend development (HTML/CSS/JS), serving static files, browser compatibility, and ongoing maintenance. This is outside dacli’s core mission of providing structured, programmatic access to documentation.

Tools like docToolchain already provide web-based documentation rendering. Adding a Web UI to dacli would duplicate that effort without clear benefit.

Decision: dacli will not include a Web UI. The project scope is limited to CLI and MCP server interfaces. References to a Web UI in existing architecture documents will be removed.

Consequences:

Positive:

Negative:

Status: Accepted (2026-02-11)

Deciders: Development Team + Claude Code

Context:

The dacli CLI module requires risk classification according to the Risk Radar framework to determine appropriate security and quality assurance measures. The assessment evaluates five dimensions:

Decision:

Classify dacli CLI as Tier 2 — Extended Assurance (determined by max(Code Type=2, Language=2, Blast Radius=2)).

This tier requires:

Consequences:

Positive:

Negative:

Status: Accepted (2026-02-11)

Deciders: Development Team + Claude Code

Context:

The dacli-mcp MCP server module requires risk classification according to the Risk Radar framework to determine appropriate security and quality assurance measures. The assessment evaluates five dimensions:

Note: Initial consideration was given to Code Type score 3 (API/Database Queries) since the module exposes API endpoints (MCP tools). However, user confirmed score 2 as these are internal service APIs without public exposure or direct database access.

Decision:

Classify dacli-mcp as Tier 2 — Extended Assurance (determined by max(Code Type=2, Language=2, Blast Radius=2)).

This tier requires the same mitigation measures as dacli CLI (both modules share the same codebase):

Consequences:

Positive:

Negative:

Status: Accepted (2026-02-11)

Deciders: Development Team + Claude Code

Context:

Following the Tier 2 risk classification for both dacli CLI and dacli-mcp modules (see ADR-011 and ADR-012), the project requires implementation of comprehensive security and quality assurance measures. The Risk Radar framework mandates cumulative mitigations: all Tier 1 measures plus all Tier 2 measures.

Both modules share the same codebase (src/dacli/), so mitigations are applied repository-wide rather than per module.

Decision:

Implement all required Tier 1 and Tier 2 mitigation measures as repository-wide protections:

Tier 1 — Automated Gates:

Tier 2 — Extended Assurance:

Security Fixes Applied:

Consequences:

Positive:

Negative:

The system must provide fast access to documentation content, even in large projects.

The system must be robust and guarantee that no data is lost or corrupted.

The system must be easy to use for its target audience of developers and architects.

The system must be able to handle large documentation projects.

This list is taken from the PRD’s risk assessment.

Technical debt consists of design or implementation choices that are expedient in the short term but may lead to future costs.

Implementation-related technical debt is tracked as GitHub issues with the tech-debt prefix. These issues document gaps between specification and implementation that are deferred for future work.