4. Solution Strategy

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

Note: This chapter has been updated (Oct 2025) to reflect the actual implemented system and document the mental model (nach Peter Naur) that guided development - not just what was built, but why it makes sense.

4.0 Mental Model: The Core Insight

Following Peter Naur’s theory that "programming is theory building," we document here the fundamental mental model that makes this architecture coherent and maintainable.

The Central Problem: Cognitive Mismatch

The core insight driving this architecture is recognizing a fundamental mismatch:

LLMs think in → Hierarchical concepts, semantic structure, logical relationships Files exist as → Linear text, physical boundaries, arbitrary splits

Traditional file-based access forces LLMs to: 1. Load entire files (wasting tokens on irrelevant content) 2. Parse structure repeatedly (expensive, error-prone) 3. Navigate via file paths (physical structure ≠ logical structure)

Mental Model: "The document is a logical tree, not a collection of text files."

This single insight explains most architectural decisions: - Why in-memory index? → Parse the logical tree once, query it many times - Why file-system-as-truth? → Preserve human editability, Git workflows - Why custom parser? → Off-the-shelf tools think in "files," we need "logical sections" - Why modular architecture? → Each module = one cognitive context

Design Philosophy: Simplicity Through Separation

The architecture separates three concerns that are often conflated:

  1. Logical Structure (what the document means)

    • Chapters, sections, hierarchy

    • Handled by: DocumentParser, Structure Index

  2. Physical Storage (where content lives)

    • Files, includes, line numbers

    • Handled by: File System, ContentEditor

  3. Access Protocol (how clients interact)

    • MCP tools, JSON-RPC, HTTP

    • Handled by: ProtocolHandler, WebServer

Mental Model: "Logical ≠ Physical ≠ Protocol"

This separation enables: - Users think in documents (logical) - Developers edit files (physical) - LLMs query via MCP (protocol)

Each dimension can evolve independently.

Key Assumptions (Mental Model Foundation)

Understanding the architecture requires understanding its assumptions:

  1. "Read-heavy workload" (90% reads, 10% writes)

    • Justifies: In-memory index, parse-once strategy

    • If false: Would need different caching strategy

  2. "Project size is bounded" (~600 pages max)

    • Justifies: In-memory approach, no pagination needed

    • If false: Would need streaming/chunking architecture

  3. "Humans are co-editors" (not just LLMs)

    • Justifies: File-system-as-truth, human-readable formats

    • If false: Could use binary/database storage

  4. "Clarity > Performance" (within reason)

    • Justifies: Modular split even with delegation overhead

    • If false: Would keep monolithic structure

  5. "One concern = One module" (cognitive load management)

    • Justifies: <500 lines per file, focused responsibilities

    • If false: Could have larger, more tightly coupled modules

These assumptions form the "theory" (Naur) that makes the code comprehensible.

Why This Architecture Makes Sense

The architecture can be understood as solving three nested problems:

Problem 1: Token Efficiency (innermost) → Solution: In-memory index enables precise content location → Mental Model: "Know where to look before you look"

Problem 2: Human Compatibility (middle) → Solution: File-system-as-truth preserves editability → Mental Model: "The file is the document, not a cache"

Problem 3: Maintainability (outermost) → Solution: Modular architecture with clear boundaries → Mental Model: "Each module = one mental context"

This nesting explains why certain decisions depend on others: - Can’t have modular architecture without clear concerns separation - Can’t have in-memory index without understanding read-heavy workload - Can’t have file-based approach without human co-editing requirement

The architecture is not just a collection of decisions - it’s a coherent theory about how to bridge the gap between LLM needs and human workflows.

4.1 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).

4.2 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.11+

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

Web Server / API

FastAPI

Provides a high-performance, MCP-compliant web server with automatic data validation and API documentation, directly supporting Usability (USAB-1, USAB-2).

Document Parsing

Custom Parser Logic

A custom parser will be developed to handle AsciiDoc/Markdown specifics, especially the critical requirement of resolving includes and tracking line numbers accurately. Off-the-shelf libraries often lack the required granularity. This directly addresses the risk of Format Variations.

Diff Engine

difflib

Python’s standard library for generating diffs, sufficient for providing real-time feedback in the web UI (Usability, USAB-3).

4.3 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 API (FastAPI)

Usability (USAB-1)

FastAPI’s strict schema validation and automatic documentation ensures the API adheres to the defined protocol.

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.