Saltar a contenido

Estado de fase (MASTER-00): POST_MVP — documento de catálogo de producto sujeto a validación; no es alcance aprobado de Gate 0 / PoC / MVP. Gobernanza: MASTER-00.

Alcance multiplataforma (DEC-002): las plataformas de producto aprobadas son Mobile (Android/iOS) y Desktop (JVM) sobre el núcleo compartido; Web (Wasm/JS) queda fuera del alcance. Desktop es el entorno operativo principal (Fase D). Ver MASTER-00 v0.7 §5 y §8.4.

DocuGraph Global Specification & Scope Boundaries

Nota de alcance vigente (DEC-013/DEC-014): este documento conserva la especificación histórica del producto multiplataforma. La implementación activa no incluye UI Compose, backend relacional ni monetización; el perfil operativo usa :docugraph-core, :docugraph-mcp, Markdown + Git, Obsidian, Gitea y el visor web.

1. Global Purpose & Product Intent

DocuGraph is an AI-assisted atomic documentation editor, visualization platform, and dependency graph engine designed for modern software engineering teams, software architects, and AI-native developers.

Core Intent

The system solves four critical industry bottlenecks: 1. Eliminating AI context window overflow and hallucinations when AI agents (Cursor, Claude Code, Copilot) generate code. 2. Eliminating documentation fragmentation and specification drift in fast-moving codebases. 3. Providing software architects with a high-performance visual 2D Directed Acyclic Graph (DAG) canvas. 4. Enabling automated, continuous verification of 100% end-to-end requirement traceability across user stories, UI screens, API endpoints, database schemas, and unit tests.

2. Explicit Scope Boundaries

To maintain software quality, crisp architecture, and rapid delivery, DocuGraph defines strict system boundaries:

2.1 In-Scope Capabilities

  1. Atomic Frontmatter DAG Engine (:docugraph-core):
  2. Parsing standard Markdown files with YAML frontmatter headers (id, title, type, status, tags, links).
  3. Constructing in-memory Adjacency List graph models.
  4. Detecting circular dependency loops using Tarjan's Strongly Connected Components (SCC) algorithm in $O(V+E)$ time.
  5. Performing reverse topological sorting to calculate pruned context subtrees.
  6. Multiplatform Compose Visual Canvas (:docugraph-app):
  7. Multiplatform desktop (JVM), mobile (Android, iOS), and Web (Wasm/JS) client built with Compose Multiplatform.
  8. Interactive 2D graph viewport supporting 60 FPS rendering, pan gestures, pinch zoom (0.25x to 3.0x), dynamic tag/type filtering, and slide-out inspector panels (NodeInspector).
  9. Kotlin Model Context Protocol Server (:docugraph-mcp):
  10. Full MCP implementation supporting Stdio (local CLI agents) and HTTP SSE (IDE/remote agents) transports.
  11. Core tools: get_task_context (reverse topological context bundle extraction), get_dependency_graph, and validate_traceability.
  12. Core resources (docugraph://workspace/...) and prompts (prompt_implement_task, prompt_audit_traceability).
  13. Relational Backend & Sync (:docugraph-backend):
  14. Ktor REST API backend with PostgreSQL storage across 6 tables (users, subscriptions, projects, nodes, node_edges, mcp_api_keys).
  15. Workspace change indexing, user auth (JWT RS256 with Argon2id/bcrypt password hashing), and cloud state sync.
  16. RevenueCat Freemium Integration:
  17. Tiered subscription management enforcing Free tier constraints (up to 3 local projects, max context traversal depth = 2) vs Pro tier (pro_tier entitlement ID, $19/mo or $190/yr).
  18. Native RevenueCat Mobile SDK integration for Android/iOS and RevenueCat REST API v1 fallback for Desktop/Web.
  19. 7-day offline JWT entitlement claim caching.

2.2 Explicit Out-of-Scope Non-Goals

  1. Not a General-Purpose Markdown Rich-Text Editor:
  2. DocuGraph does NOT replace text editors like Obsidian, Notion, or Typora. It parses and visualizes existing Markdown files residing in user Git repositories without modifying arbitrary text body content.
  3. Not an LLM Runner or Local Model Execution Engine:
  4. DocuGraph does NOT bundle, fine-tune, or execute local LLM binaries (e.g., Llama.cpp, Ollama, vLLM). It serves formatted Markdown context bundles to external AI coding agents via standard MCP protocols.
  5. No Proprietary Binary Storage Formats:
  6. All documentation source files remain 100% human-readable Markdown (.md) and YAML (.yaml) files. DocuGraph does NOT enforce proprietary binary file lock-in.
  7. Not a Git Code Repository Hosting Service:
  8. DocuGraph integrates with Git remote URLs for metadata tracking and commit checksum linkage, but does NOT host Git repositories or act as a code repository manager (not a GitHub or GitLab replacement).
  9. No Real-Time Multi-Cursor Collaborative Text Buffers:
  10. Synchronization takes place at the relational index and DAG graph model level, not real-time operational transformation (OT) or Conflict-Free Replicated Data Type (CRDT) live text buffer editing.

3. Target Product Stack Definition

Subsystem / Layer Technology / Library Version / Baseline Operational Purpose
Core Engine Kotlin Multiplatform (KMP) Kotlin 1.9+ Shared logic across all client/server targets
kotlinx.serialization 1.6+ JSON & YAML serialization
KMP YAML Parser / snakeyaml Latest stable Parsing Markdown YAML frontmatter blocks
Kotlin Coroutines & Flow 1.7+ Asynchronous graph computation & processing
Client UI Compose Multiplatform 1.6+ Declarative multiplatform UI rendering
Mobile Platforms Android API 34+, iOS 15+ Android & iOS mobile applications
Desktop & Web Java 17+ JVM, Web Wasm/JS Desktop app & Web canvas browser client
MCP Server Kotlin MCP SDK Latest standard Standardized MCP protocol integration
Transports Stdio & Ktor HTTP SSE Communication with local CLI and IDE AI agents
Backend Service Ktor Framework 2.3+ Asynchronous REST API routing & websockets
Exposed ORM & HikariCP 0.45+ Relational ORM mapping & connection pooling
Auth & Security JWT RS256, Argon2id Cryptographic session tokens & password hashing
Database PostgreSQL 15+ Persistent relational index for 6 core tables
Monetization RevenueCat SDK / REST API v1 Mobile SDK / REST v1 In-app purchases, billing, & entitlement caching
Build & Tooling Gradle Monorepo 8.5+ Multi-module build management

4. Core Technical Principles

Principle 1: Pure Atomic Documentation

Every documentation file is a single, self-contained unit of technical specification. Every file MUST begin with a standard YAML frontmatter block declaring id, title, type, status, tags, and links.

Principle 2: Zero Content Duplication

Content is never copy-pasted across files. Authoritative single sources of truth are established across the workspace: - REST API Contracts: docs/api/openapi.yaml (operationId) - Database Schemas: docs/domain/01_DATABASE_SCHEMA.md (table: XXX) - Business Strategy & Monetization: docs/00_BUSINESS_VISION.md (VISION-00)

Principle 3: ID-Based Explicit Linking

Downstream documents cite explicit upstream atomic IDs (US-XX, IX-XX, FE-XX, BE-XX, operationId, table: XXX). Relationships (depends_on, depended_by, related, tables) form the edges of the system DAG.

Principle 4: AI Context Minimization

The MCP tool get_task_context uses reverse topological graph traversal starting from a target task ID. It collects only directly required upstream specifications and prunes all unreferenced subtrees, returning minimal Markdown context bundles to eliminate token waste.

Principle 5: Multi-Tenancy & Offline Grace Period

Entitlement claims (pro_tier) are embedded directly into JWT access tokens. Client applications and local MCP servers validate entitlements offline for up to 7 consecutive days before requiring online verification.

5. Non-Functional Requirements & Quality Attributes

5.1 Performance

  • Visual Canvas Rendering: Render visual graphs containing up to 1,000 nodes and 2,500 edges at a smooth 60 FPS viewport frame rate.
  • Context Extraction Latency: The MCP server MUST generate and return pruned Markdown context bundles for get_task_context queries in under 150 milliseconds.
  • Traceability Audit Speed: Tarjan's SCC cycle detection and link verification across a 1,000-node workspace MUST execute in under 2.0 seconds.

5.2 Security

  • Credential Hashing: User passwords MUST be hashed using Argon2id or bcrypt with high work factors.
  • Token Signing: Access JWT tokens MUST be signed using RS256 asymmetric keys.
  • Platform Key Storage: Mobile and desktop clients MUST store sensitive JWT refresh tokens and MCP API keys in OS-native encrypted storage (EncryptedSharedPreferences on Android, Keychain on iOS/macOS, Secret Service/Keyring on Linux/Windows).

5.3 Reliability & Resilience

  • Offline Tolerance: Graph canvas viewing, local workspace searching, and cached JWT entitlement checks MUST operate fully offline.
  • Graceful Fallback: If desktop JVM platforms cannot access native RevenueCat SDKs, they fall back seamlessly to RevenueCat REST API v1 over HTTPS.

6. Traceability Index