Saltar a contenido

DocuGraph Domain Glossary & Atomic Documentation Taxonomy

1. Executive Summary & Purpose

This domain glossary defines the authoritative technical vocabulary, algorithmic terms, architectural concepts, and domain taxonomy used throughout the DocuGraph platform, monorepo codebase, and documentation specifications.

2. Core Domain Taxonomy & Term Definitions

1. Frontmatter

  • Formal Definition: A structured metadata header in YAML format embedded at the very top of a Markdown file, delimited by triple hyphens (---).
  • DocuGraph Context: Serves as the primary declaration of identity, status, tags, and directed relationships (depends_on, depended_by, related, tables) for an atomic documentation node.
  • Technical Impact: Parsed by :docugraph-core to populate the nodes and node_edges tables in PostgreSQL (SCHEMA-01). Every valid DocuGraph file MUST start with a valid frontmatter block.

2. Atomic Node

  • Formal Definition: A single-purpose, discrete documentation unit representing an indivisible architectural component, user requirement, interaction flow, UI composable, backend service, or database schema.
  • DocuGraph Context: Identified by unique atomic ID prefixes (US-XX, IX-XX, FE-XX, BE-XX, SCHEMA-XX, GLOSSARY-XX). Adheres strictly to the zero-content-duplication principle by citing upstream IDs instead of copying text.
  • Technical Impact: Stored as individual records in the nodes database table.

3. Directed Acyclic Graph (DAG)

  • Formal Definition: A finite directed graph structure consisting of vertices (nodes) connected by directed edges containing zero directed cycles.
  • DocuGraph Context: Represents the global dependency structure of a DocuGraph project workspace. Nodes represent specifications, while directed edges represent explicit depends_on relationships.
  • Technical Impact: Guarantees that system documentation flows unidirectionally without circular references. Enables reverse topological sorting and automated cycle validation.

4. Traversal Depth

  • Formal Definition: The maximum number of directed edge steps (hops) traversed from a target starting node during graph traversal algorithms.
  • DocuGraph Context: Governs the depth of context extracted by the MCP tool get_task_context.
  • Technical Impact: Enforces freemium monetization boundaries (VISION-00). Free tier users are capped at maxDepth = 2, whereas Pro tier subscribers (pro_tier) enjoy unlimited traversal depth.

5. MCP Context Bundle

  • Formal Definition: A single, consolidated Markdown document generated dynamically by the Model Context Protocol (MCP) server (:docugraph-mcp) upon receiving a get_task_context query.
  • DocuGraph Context: Contains only the target task node and its pruned upstream dependencies arranged in logical topological sequence.
  • Technical Impact: Serves hyper-focused task context to AI coding agents (Cursor, Claude Code, Copilot), preventing AI context window overflow and eliminating hallucinations.

6. Entitlement

  • Formal Definition: An authorized access right associated with a user account that unlocks premium system capabilities or removes capacity constraints.
  • DocuGraph Context: Managed via RevenueCat integration (US-06). The core entitlement ID pro_tier unlocks unlimited projects, unlimited context traversal depth, PostgreSQL cloud sync, and automated CI/CD audits.
  • Technical Impact: Tracked in the subscriptions database table (SCHEMA-01).

7. Entitlement Claim

  • Formal Definition: A cryptographically signed key-value pair (entitlement: "pro_tier") embedded within an authenticated JSON Web Token (JWT) issued by :docugraph-backend.
  • DocuGraph Context: Enables local, offline verification of Pro feature access across client applications (Compose Multiplatform app and local MCP server) without network latency.
  • Technical Impact: Cached in local platform secure storage for up to 7 consecutive days (offline_grace_until).

8. RevenueCat Pro

  • Formal Definition: The commercial subscription service ($19/month or $190/year) integrated into DocuGraph via native RevenueCat SDKs (mobile) and RevenueCat REST API v1 (desktop/server).
  • DocuGraph Context: Handles in-app purchase dialogs (FE-05 PaywallModal), billing receipts, cross-device subscription restoration, and webhook event processing.
  • Technical Impact: Synchronizes purchase events with the backend subscriptions table.

9. Tarjan's Algorithm

  • Formal Definition: A graph theory algorithm developed by Robert Tarjan that computes the Strongly Connected Components (SCCs) of a directed graph in linear time $O(|V| + |E|)$.
  • DocuGraph Context: Utilized by :docugraph-core and the validate_traceability MCP tool to perform automated cycle detection across workspace documentation nodes.
  • Technical Impact: Identifies invalid circular dependency loops (e.g. Node A $\to$ Node B $\to$ Node A) and produces actionable diagnostic error logs with file paths and line numbers.

10. Topological Sort

  • Formal Definition: A linear ordering of vertices in a Directed Acyclic Graph such that for every directed edge $u \to v$, node $u$ appears before node $v$ in the sequence.
  • DocuGraph Context: Used by :docugraph-core during MCP context extraction (get_task_context) to order dependencies in natural hierarchy (e.g., Business Vision $\to$ User Story $\to$ Interaction Spec $\to$ OpenAPI Contract $\to$ DB Schema $\to$ Backend Task).
  • Technical Impact: Ensures AI coding agents process technical context in logical prerequisite order.

3. Traceability Index