ADR

Architecture Decision Record. A document that captures an important architectural decision and its context and consequences. This project has 8 ADRs (see Chapter 9).

AST

Abstract Syntax Tree. A tree representation of the abstract syntactic structure of source code. In our case, of a documentation project.

Atomic Write

An operation that is guaranteed to either complete fully or not at all, preventing partially-written, corrupted data. Implemented via backup-and-replace strategy (ADR-004).

Hierarchical Path

A human-readable path used to identify a specific section within the documentation project, e.g., chapter-1.section-2. Encodes the logical structure.

MCP

Model Context Protocol. A JSON-RPC based specification for how LLM-based agents should interact with external tools and data sources. This server implements MCP v1.0.

Mental Model (nach Naur)

The coherent theory that makes the code comprehensible. Documenting not just "what" was built, but "why" it makes sense. See Chapter 4.0.

Section

The fundamental unit of documentation - a logical chunk with a heading, content, and hierarchical position. Represented by the Section dataclass (see Chapter 5.4).

Structure Index

The in-memory data structure (Dict[str, Section]) that holds the metadata of the entire documentation project for fast O(1) lookups. See ADR-002.

Dependency Injection

Pattern where modules receive dependencies (like the server instance) rather than creating them. Avoids circular dependencies. See Chapter 8.4.

Extract-and-Delegate

Pattern where a thin orchestrator creates focused modules and delegates to them. Used in MCPDocumentationServer (ADR-006). See Chapter 8.4.

File-System-as-Truth

Pattern where files are the source of truth, not a cache. In-memory index is a performance optimization. See ADR-001 and Chapter 8.4.

Parse-Once, Query-Many

Pattern optimized for read-heavy workloads. Parse project once on startup, then serve queries from in-memory index. See Chapter 8.4.

ContentEditor

Module (content_editor.py) responsible for atomic file modifications. Uses backup-and-replace strategy.

DocumentAPI

Module (document_api.py) implementing all document operations (get_structure, search_content, etc.). See ADR-006.

DocumentParser

Module (document_parser.py) that parses AsciiDoc/Markdown files and resolves includes. Custom implementation (ADR-005).

FileWatcher

Module (file_watcher.py) that monitors file system changes using the watchdog library and triggers auto-refresh. Added in Oct 2025.

ProtocolHandler

Module (protocol_handler.py) implementing MCP JSON-RPC protocol parsing and routing. See ADR-006.

WebserverManager

Module (webserver_manager.py) managing web server lifecycle, port finding, and browser auto-launch. See ADR-006.

Coverage

Percentage of code lines executed by tests. Project achieved 82% overall, 100% for critical modules (ADR-008).

Pytest

Testing framework used for all tests. Chosen for simplicity and fixture support (ADR-008).

Test Pyramid

Testing strategy with many unit tests, some integration tests, few end-to-end tests. See Chapter 8.5.

TDD (Test-Driven Development)

Development workflow: write failing test → implement → verify passing. User’s global instruction, followed throughout project.

Deferred Feature

Feature consciously moved to future (not forgotten). Example: Real-time diff display moved to v3.0. See Chapter 11.4.

PRD

Product Requirements Document. Specification of what should be built. Project has v1.0 (original vision) and v2.0 (actual state).

Technical Debt

Code shortcuts that need future cleanup. Project started with 4 debts, repaid 3 (see Chapter 11.3).

Debouncing

Technique to batch multiple rapid file change events to avoid re-parsing storm. File watcher uses 500ms debounce.

In-Memory Index

Performance optimization storing parsed structure in RAM (Dict[str, Section]). Enables <100ms API response times.

O(1) Lookup

Constant-time operation regardless of data size. Structure index provides O(1) section lookups by path.

FastAPI

Python web framework used for HTTP API and web UI. Provides automatic validation and OpenAPI docs.

Uvicorn

ASGI server that runs the FastAPI application. Supports async operations.

Watchdog

Python library for monitoring file system events (inotify on Linux, FSEvents on macOS). Used for auto-refresh.