Solution Strategy

This chapter outlines the fundamental architectural decisions and strategies to meet the requirements defined in the previous chapters.

Core Architectural Approach: In-Memory Index with File-System-as-Truth

The core of the architecture is a dual approach:

  1. In-Memory Index: On startup, the server parses the entire documentation project and builds a lightweight, in-memory index of the document structure (files, sections, line numbers, includes). This index is the key to achieving the Performance goals (PERF-1), as it allows for near-instant lookups of content locations without repeatedly reading files from disk.

  2. File System as the Single Source of Truth: The system is stateless. The file system holds the definitive state of the documentation at all times. All modifications are written directly back to the source files. This approach satisfies the constraints of Human-Readable Files and Version Control Integration. It also simplifies the architecture by avoiding the need for a database (Constraint: File-System Based).

Technology Decisions

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.

Table 1. Proposed Technology Stack

Component

Technology

Justification

Language

Python 3.12+

Excellent for text processing, large standard library, strong community support, and mature libraries for parsing.

Package Manager

uv

Ultra-fast Python package installer and resolver. Provides deterministic builds via uv.lock, faster dependency resolution than pip/poetry, and integrated virtual environment management.

MCP Framework

FastMCP

High-level framework for building MCP servers in Python. Simplifies tool registration, handles MCP protocol details, and provides stdio transport.

CLI Framework

Click

Mature Python CLI framework for building the dacli command-line interface.

Document Parsing

Custom Parser Logic

Custom parsers handle AsciiDoc/Markdown specifics, especially resolving includes and tracking line numbers accurately. Off-the-shelf libraries often lack the required granularity. This directly addresses the risk of Format Variations.

Development Environment Setup

The project uses uv for Python environment and dependency management:

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv sync

# Run the server
uv run dacli-mcp

# Add a new dependency
uv add <package-name>

# Add a development dependency
uv add --dev <package-name>

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

Achieving Key Quality Goals

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

Table 2. Strategy-to-Quality-Goal Mapping

Strategy

Quality Goal Addressed

How it is achieved

In-Memory Structure Index

Performance (PERF-1, PERF-2)

Read operations query the fast in-memory index for file locations instead of parsing files on every request.

Atomic Write-Through Cache

Reliability (REL-1, REL-3)

A File System Handler component implements atomic writes by using temporary files and backups. This prevents file corruption.

MCP-Compliant Tools (FastMCP)

Usability (USAB-1)

FastMCP handles MCP protocol compliance, tool registration, and stdio transport. Tools are strongly typed with clear parameter definitions.

Dual Interface (CLI + MCP)

Usability (USAB-2)

Both CLI (for direct use) and MCP server (for LLM integration) share the same core logic, ensuring consistent behavior.

Stateless, File-Based Design

Scalability (SCAL-1) & Reliability

By keeping the server stateless, scaling becomes simpler (less state to manage). It also improves reliability as there is no complex database state to corrupt or manage.