DocuGraph Master Project Delivery & Implementation Plan

Catálogo histórico

Este documento no forma parte del modo operativo. El filtro del menú lo oculta por defecto.

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.

DocuGraph Master Project Delivery & Implementation Plan

Nota de alcance vigente (DEC-013/DEC-014): este plan conserva el catálogo histórico de spikes y entregables multiplataforma. La implementación activa no mantiene :docugraph-app ni :docugraph-backend; la ejecución vigente se centra en :docugraph-core, :docugraph-mcp, Git, Oracle y el visor web.

1. EXECUTIVE SUMMARY & DELIVERY OBJECTIVES

1.1 Project Purpose & Core Objectives

The DocuGraph Master Project Delivery & Implementation Plan defines the engineering roadmap, technical spikes, milestone breakdown, risk governance, and resource allocation required to build, test, and deploy DocuGraph v0.01.

DocuGraph is an AI-assisted atomic documentation editor and dependency graph engine built as a multiplatform monorepo (:docugraph-core, :docugraph-app, :docugraph-mcp, :docugraph-backend). The software enables developers and architects to convert static project documentation into an interactive Directed Acyclic Graph (DAG) and provides AI coding agents (such as Claude Code, Cursor, and Copilot) with exact, non-overflowing context bundles via the Model Context Protocol (MCP).

1.2 Governance Principles & Delivery Strategy

1. Atomic Traceability Compliance: Implementation progress strictly adheres to the 34-file documentation inventory in docs/01_PROJECT_MANIFEST.md (MANIFEST-01) and the requirements baseline in docs/srs/SRS_IEEE-830.md (SRS-830).
2. De-Risked Spikes-First Execution: High-risk architectural assumptions (Compose 60 FPS viewport rendering, Tarjan SCC cycle detection, MCP transports, hybrid RevenueCat offline JWT claims, high-speed frontmatter parsing, and PostgreSQL ORM performance) are systematically validated through six formal technical spikes (SPIKE-01 through SPIKE-06) prior to full-scale feature integration.
3. Multiplatform Monorepo Architecture: Strict separation of concerns across pure Kotlin Multiplatform core domain logic (:docugraph-core), Compose Multiplatform client UI (:docugraph-app), Kotlin MCP SDK server (:docugraph-mcp), and Ktor / PostgreSQL relational backend (:docugraph-backend).

---

2. TECHNICAL SPIKES & PROOFS OF CONCEPT

To eliminate technical uncertainty before core implementation, six technical spikes are specified with explicit evaluation criteria, risk hypotheses, and target deliverables:

+-----------------------------------------------------------------------------------+
|                        Technical Spikes Inventory (SPIKE-01..06)                  |
+-----------------------------------------------------------------------------------+

[ SPIKE-01: Compose Canvas Viewport ] ---> Target Module: :docugraph-app (60 FPS @ 1k Nodes)
[ SPIKE-02: KMP Tarjan SCC Traversal ] ---> Target Module: :docugraph-core (<2.0s Cycle Audit)
[ SPIKE-03: Kotlin MCP SDK Transports] ---> Target Module: :docugraph-mcp (Stdio & SSE JSON-RPC)
[ SPIKE-04: RevenueCat Offline JWT   ] ---> Target Module: :docugraph-backend (7-Day Offline Grace)
[ SPIKE-05: Markdown Frontmatter Sync] ---> Target Module: :docugraph-core (<500ms Cold Scan)
[ SPIKE-06: PostgreSQL GIN Indexing  ] ---> Target Module: :docugraph-backend (5,000 Edges/sec)

2.1 SPIKE-01: Compose Multiplatform Canvas Viewport & Graph Layout Rendering

• Identifier: SPIKE-01
• Target Module: :docugraph-app
• Objective: Evaluate custom Compose Multiplatform Canvas performance during real-time 60 FPS pan and pinch-zoom (0.25x to 3.0x scale) viewport transformations over graphs containing 1,000 nodes and 2,500 edges.
• Evaluation Criteria:
  • Viewport rendering maintains $\ge 60$ FPS during continuous pan and zoom gesture interactions.
  • Spatial bounding-box viewport culling limits rendered drawn primitives to visible nodes and edges.
  • Force-directed layout algorithm computation time completes in $< 300$ ms for 1,000 nodes on Desktop (JVM) and Mobile (Android/iOS).
• Risk Hypothesis: Unoptimized Compose Canvas rendering without spatial indexing will cause frame drops below 30 FPS on mobile devices when rendered node counts exceed 250.
• Target Deliverable: Standalone Compose prototype in :docugraph-app with benchmark report and Skiko spatial index implementation.

2.2 SPIKE-02: KMP Core DAG Traversal & Tarjan SCC Cycle Detection Benchmarking

• Identifier: SPIKE-02
• Target Module: :docugraph-core
• Objective: Benchmark pure Kotlin Multiplatform implementations of Tarjan’s Strongly Connected Components (SCC) cycle detection algorithm ($O(V+E)$) and reverse topological sorting across JVM, Native (iOS), and Android runtime targets.
• Evaluation Criteria:
  • Cycle detection across 1,000 nodes and 2,500 edges completes in $< 2.0$ seconds.
  • Reverse topological traversal starting from a target node (get_task_context) completes in $< 150$ ms.
  • Heap memory allocation during graph traversal remains strictly below 16 MB.
• Risk Hypothesis: Recursive graph traversal algorithms will trigger StackOverflowError or memory spikes on deeply nested dependency DAGs.
• Target Deliverable: Multiplatform unit benchmark suite in :docugraph-core utilizing kotlinx-benchmark with memory profile metrics.

2.3 SPIKE-03: Kotlin MCP SDK Transports & JSON-RPC Protocol Correctness

• Identifier: SPIKE-03
• Target Module: :docugraph-mcp
• Objective: Validate official Kotlin MCP SDK (io.modelcontextprotocol.sdk) integration across dual transports: StdioServerTransport (for local CLI tools like Claude Code, Cursor) and ServerSentEventsServerTransport (for remote IDE and web clients).
• Evaluation Criteria:
  • 100% JSON-RPC 2.0 protocol compliance with Model Context Protocol specification v1.0.
  • Latency for tool execution (get_task_context, get_dependency_graph, validate_traceability) remains $< 150$ ms over both Stdio and SSE transports.
  • Graceful connection pooling and resource cleanup under 100 concurrent SSE clients.
• Risk Hypothesis: Blocking I/O on Stdio transport will cause thread starvation in asynchronous Ktor coroutine contexts.
• Target Deliverable: PoC executable server in :docugraph-mcp verified against standard MCP client test harnesses.

2.4 SPIKE-04: Multiplatform RevenueCat Entitlement & Offline JWT Caching Mechanism

• Identifier: SPIKE-04
• Target Modules: :docugraph-core, :docugraph-backend, :docugraph-app
• Objective: Validate hybrid monetization architecture combining native RevenueCat Mobile SDKs (Android/iOS) with RevenueCat REST API v1 fallback (Desktop JVM/Web) and offline RS256 JWT claim verification.
• Evaluation Criteria:
  • Seamless entitlement claim (pro_tier) resolution across native SDKs and REST v1 fallback.
  • Offline entitlement validation operates securely for up to 7 consecutive days via cached RS256 signed JWTs (offline_grace_until).
  • Strict enforcement of Free tier limits (max 3 projects, max context depth = 2) vs Pro tier unlock.
• Risk Hypothesis: Local device clock tampering could allow unauthorized extension of offline grace periods.
• Target Deliverable: Cryptographic security validation suite and unified entitlement manager interface in :docugraph-core.

2.5 SPIKE-05: High-Speed Markdown YAML Frontmatter Parsing & Incremental File Sync

• Identifier: SPIKE-05
• Target Module: :docugraph-core
• Objective: Evaluate YAML frontmatter parsing performance and prototype an incremental file hash (sha256) index scanner for local workspace directories.
• Evaluation Criteria:
  • Initial cold scan and YAML frontmatter parsing of 1,000 Markdown files completes in $< 500$ ms.
  • Incremental rescan of modified workspace files completes in $< 50$ ms.
  • 100% accurate extraction of atomic metadata (id, title, type, status, tags, links).
• Risk Hypothesis: Full re-parsing of large Markdown body texts during workspace open will degrade application startup speed.
• Target Deliverable: Multiplatform frontmatter benchmark module and incremental scanner implementation in :docugraph-core.

2.6 SPIKE-06: PostgreSQL GIN Indexing & Ktor Relational Graph Sync

• Identifier: SPIKE-06
• Target Module: :docugraph-backend
• Objective: Benchmark PostgreSQL 15 performance for graph node indexing, GIN indexing on array tags (tags text[]) and JSONB frontmatters (frontmatter jsonb), and Exposed ORM query execution under concurrent write loads.
• Evaluation Criteria:
  • Batch insertion rate $\ge 5,000$ edges/sec during initial workspace database sync.
  • Graph adjacency query (buildGraph) latency $< 100$ ms for 1,000 nodes and 2,500 edges.
  • HikariCP connection pool stability under 100 concurrent SSE/REST requests.
• Risk Hypothesis: Complex recursive graph queries in SQL will cause lock contention on node_edges during continuous change sync.
• Target Deliverable: Database benchmark scripts (JMeter / Gatling) and optimized PostgreSQL DDL configuration in :docugraph-backend.

---

3. PHASE DELIVERABLES, MILESTONES & WORK BREAKDOWN STRUCTURE

3.1 Milestone Execution Roadmap

The delivery lifecycle is organized across six sequential milestones (M1 through M6):

+------------------------------------------------------------------------------------+
|                         Milestone Execution Roadmap                                |
+------------------------------------------------------------------------------------+

[ M1: Foundation & User Stories ] (DONE - 9 Files)
              |
              v
[ M2: System Manifest & Specs   ] (DONE - 9 Files)
              |
              v
[ M3: OpenAPI & Component Specs ] (DONE - 13 Files)
              |
              v
[ M4: SRS, Plan & Test Suite    ] (IN_PROGRESS - 3 Files + Manifest Alignment)
              |
              v
[ M5: Core Engine & Backend     ] (PLANNED - Spikes, :docugraph-core, :docugraph-backend)
              |
              v
[ M6: Multiplatform UI & Launch ] (PLANNED - :docugraph-app Compose UI, Release Binaries)

Milestone Summary Matrix

Milestone ID	Name	Core Focus & Target Deliverables	Target Artifacts	Status
M1	Foundation, Product Vision & User Stories	Define business vision, freemium revenue model, personas, and 6 core user stories.	README.md, AGENTS.md, 00_BUSINESS_VISION.md, US-01 .. US-06 (9 files)	APPROVED
M2	System Manifest, Global & Domain Specs	Central manifest, 100% traceability matrix, global scope, architecture, DB schema, glossary, 4 interaction specs.	01_PROJECT_MANIFEST.md, 02_GLOBAL_SPEC.md, 03_ARCHITECTURE.md, SCHEMA-01, GLOSSARY-01, IX-01 .. IX-04 (9 files)	APPROVED
M3	OpenAPI Contract, Backend, Frontend & MCP Specs	Canonical OpenAPI 3.1.0 contract, 6 backend task specs, 5 frontend composable specs, Kotlin MCP server spec.	openapi.yaml, BE-01 .. BE-06, FE-01 .. FE-05, MCP_SPEC.md (13 files)	APPROVED
M4	IEEE 830 SRS, Master Plan, Test Suite & Audit	IEEE 830 SRS, Master Project Plan, Master Test Plan, and automated 34-file workspace audit verification.	SRS_IEEE-830.md, PLAN-01_delivery-plan.md, TEST-01_verification-plan.md (3 files) & Manifest Audit	IN_PROGRESS
M5	Core Engine & Relational Backend Implementation	Implement :docugraph-core engine, execute spikes SPIKE-01..06, build :docugraph-backend REST API and PostgreSQL ORM.	Monorepo (:docugraph-core, :docugraph-backend, :docugraph-mcp)	PLANNED
M6	Multiplatform UI & Production Release	Build :docugraph-app Compose Multiplatform UI, integrate RevenueCat SDK/REST fallback, release multiplatform binaries.	Monorepo (:docugraph-app) & Build Artifacts	PLANNED

---

3.2 Detailed Work Breakdown Structure (WBS)

WBS 1.0 Milestone M1: Foundation & User Stories [APPROVED]
├── 1.1 Project Setup & AGENTS Guidelines (README.md, AGENTS.md)
├── 1.2 Business Vision & RevenueCat Freemium Strategy (docs/00_BUSINESS_VISION.md)
└── 1.3 Core User Stories Setup (US-01 Login, US-02 Project, US-03 Graph, US-04 Context, US-05 Audit, US-06 RevenueCat)

WBS 2.0 Milestone M2: System Manifest, Architecture & Domain Specs [APPROVED]
├── 2.1 System Manifest & 100% End-to-End Traceability Matrix (docs/01_PROJECT_MANIFEST.md)
├── 2.2 Global Specification & Scope Boundaries (docs/02_GLOBAL_SPEC.md)
├── 2.3 System Architecture & Sequence Diagrams (docs/03_ARCHITECTURE.md)
├── 2.4 Domain Database Schema & Glossary (docs/domain/01_DATABASE_SCHEMA.md, 02_GLOSSARY.md)
└── 2.5 Interaction Specifications (IX-01 Auth, IX-02 Project, IX-03 Graph, IX-04 MCP Context Flow)

WBS 3.0 Milestone M3: OpenAPI Contract & Component Specs [APPROVED]
├── 3.1 OpenAPI 3.1.0 REST Contract Specification (docs/api/openapi.yaml)
├── 3.2 Backend Task Specifications (BE-01 Auth, BE-02 Project, BE-03 Graph, BE-04 Context, BE-05 Audit, BE-06 Paywall)
├── 3.3 Frontend Component Specifications (FE-01 Login, FE-02 Dashboard, FE-03 Canvas, FE-04 Inspector, FE-05 Paywall)
└── 3.4 Kotlin MCP Protocol Specification (docs/mcp/MCP_SPEC.md)

WBS 4.0 Milestone M4: SRS IEEE 830, Project Plan & Master Test Suite [IN_PROGRESS]
├── 4.1 IEEE 830 System Requirements Specification (docs/srs/SRS_IEEE-830.md)
├── 4.2 Master Project Delivery & Implementation Plan (docs/project_plan/PLAN-01_delivery-plan.md)
├── 4.3 Master Testing & Verification Plan (docs/testing/TEST-01_verification-plan.md)
└── 4.4 Automated Workspace Traceability & Integrity Audit (34-File Manifest Verification)

WBS 5.0 Milestone M5: Core Engine & Relational Backend Implementation [PLANNED]
├── 5.1 Technical Spikes Execution (SPIKE-01 through SPIKE-06)
├── 5.2 KMP Core Engine Implementation (:docugraph-core: YAML Parser, Tarjan SCC Engine, Topological Sorter)
├── 5.3 Backend REST API & PostgreSQL Service (:docugraph-backend: Ktor Routes, Exposed ORM, JWT Auth, Entitlements)
└── 5.4 Kotlin MCP Server Transports & Tools (:docugraph-mcp: Stdio Transport, SSE Transport, Tool/Resource/Prompt Handlers)

WBS 6.0 Milestone M6: Compose UI Client & Release Packaging [PLANNED]
├── 6.1 Compose Multiplatform Viewport Canvas (:docugraph-app: FE-03 GraphCanvas, FE-04 NodeInspector)
├── 6.2 Application Navigation & RevenueCat Paywall (:docugraph-app: FE-01, FE-02, FE-05, RevenueCat SDK Integration)
├── 6.3 Tier 1..4 Verification Suite & Automated CI Build Pipeline (Multiplatform builds, E2E verification)
└── 6.4 Release Packaging & Production Launch (Android APK/AAB, iOS IPA, Desktop JVM Installers, Web Wasm)

---

4. COMPREHENSIVE RISK MATRIX

Risks are evaluated across four categories: Technical, Architectural, Security, and Integration.

4.1 Scoring Legend

• Likelihood: Low (1), Medium (2), High (3)
• Impact: Low (1), Medium (2), High (3), Critical (4)
• Risk Score: Low (1-2), Medium (3-5), High (6-8), Critical (9-12)

4.2 Risk Matrix Table

Risk ID	Category	Risk Description	Likelihood	Impact	Score	Mitigation Strategy	Contingency Plan
RISK-TECH-01	Technical	Canvas viewport rendering drops below 60 FPS on large graphs (>1,000 nodes, 2,500 edges) in Compose Multiplatform.	Medium (2)	High (3)	High (6)	Implement spatial bounding-box viewport culling and spatial QuadTree indexing (SPIKE-01).	Fall back to simplified visual node rendering (circles without text labels during rapid pan/zoom) when node count $>500$.
RISK-TECH-02	Technical	High memory overhead during deep reverse topological graph traversals (get_task_context).	Low (1)	High (3)	Medium (3)	Cache parsed AST frontmatters and precomputed topological subtrees using file sha256 checksums. Default maxDepth = 5.	Enforce iterative stack-based traversal instead of recursion with hard 16 MB heap cap per request.
RISK-ARCH-01	Architectural	User-created circular dependency loops deadlock graph algorithms or cause infinite traversal recursion.	High (3)	Critical (4)	Critical (12)	Enforce mandatory Tarjan SCC cycle detection before graph traversal; reject cycle-completing edge edits; surface immediate UI errors.	Temporarily break cycle edges for read operations, flag offending nodes with status: INVALID_CYCLE, and report via audit tool.
RISK-ARCH-02	Architectural	Specification drift between docs/api/openapi.yaml contracts and backend implementation code.	Medium (2)	High (3)	High (6)	Establish openapi.yaml as single authoritative source of truth; generate Ktor route stubs and automated contract verification tests.	Continuous integration pipeline automatically fails builds if any endpoint response schema diverges from openapi.yaml.
RISK-SEC-01	Security	RevenueCat Pro entitlement tampering or client clock manipulation to bypass Free tier limits (maxDepth > 2).	Medium (2)	High (3)	High (6)	Cryptographically sign offline_grace_until claims in RS256 JWT access tokens issued by backend.	Server-side validation of all MCP API key requests (table: mcp_api_keys); immediately revoke API keys linked to tampered tokens.
RISK-SEC-02	Security	Unauthorized local or remote access to sensitive workspace documentation via unauthenticated MCP endpoints.	Low (1)	High (3)	Medium (3)	Mandate X-MCP-API-KEY header authentication for SSE transport; lock Stdio transport to local child process execution.	Automatic IP rate-limiting and connection termination on SSE endpoint upon 3 consecutive authentication failures.
RISK-INT-01	Integration	RevenueCat REST API v1 unreachability on Desktop JVM platforms during entitlement verification.	Low (1)	Medium (2)	Low (2)	Implement 7-day local offline JWT entitlement caching (offline_grace_until).	Fall back gracefully to cached Free tier capabilities after grace period expires without corrupting local user workspace data.
RISK-INT-02	Integration	Skiko / Compose Multiplatform rendering discrepancies across macOS, Windows, Linux, Android, and iOS.	Medium (2)	Medium (2)	Medium (4)	Use standardized Compose core components and abstract platform-specific canvas rendering via Skiko unified graphics layer.	Maintain platform-specific expect/actual renderer implementations for gesture handling and high-DPI scaling.

---

5. RESOURCE ALLOCATION & TIMELINE GOVERNANCE

5.1 Team Role Allocation Matrix

Role	Headcount	Primary Responsibilities	Target Modules / Artifacts
Lead Systems Architect & Core Engineer	1.0 FTE	Monorepo architecture, KMP core engine, Tarjan SCC cycle detection, topological sorter, YAML parser.	:docugraph-core, 03_ARCHITECTURE.md, SPIKE-02, SPIKE-05
Frontend & Multiplatform UI Engineer	1.5 FTE	Compose Multiplatform UI components, GraphCanvas 60 FPS viewport, NodeInspector, RevenueCat paywall modal.	:docugraph-app, FE-01..FE-05, SPIKE-01
Backend & MCP Server Engineer	1.0 FTE	Ktor REST API framework, PostgreSQL Exposed ORM, Kotlin MCP SDK server, Stdio & SSE transports, JWT auth.	:docugraph-backend, :docugraph-mcp, BE-01..BE-06, MCP_SPEC.md, SPIKE-03, SPIKE-04, SPIKE-06
QA & CI/CD Automation Lead	0.5 FTE	Tier 1..4 testing suite implementation, automated 34-file traceability audit runner, GitHub Actions build matrix.	TEST-01_verification-plan.md, 01_PROJECT_MANIFEST.md, CI/CD pipelines

5.2 Hardware, Infrastructure & Tooling Resources

• Development Workstations: Multi-core workstations (Apple Silicon M-series / x86_64 Linux, $\ge 32$ GB RAM) capable of compiling KMP iOS, Android, Desktop JVM, and Web Wasm binaries.
• CI/CD Infrastructure: GitHub Actions runners (Ubuntu x64 + macOS M1 instances for native iOS build compilation).
• Staging / Production Environment: Managed PostgreSQL 15 database instance, Ktor container hosting (Docker / Kubernetes).
• Monetization Credentials: RevenueCat sandbox environment linked with Google Play Console and Apple App Store Connect test credentials.

5.3 Execution Schedule & Target Timeline

Timeline Overview (Sprints 1 through 12):
Sprints 1-2 (M1 & M2): Requirements, Business Vision, Global Spec, DB Schema, Interaction Specs [APPROVED]
Sprints 3-4 (M3)     : OpenAPI Contract, Backend Task Specs, Frontend Specs, MCP Spec [APPROVED]
Sprint  5   (M4)     : IEEE 830 SRS, Master Project Plan, Master Test Plan, Traceability Audit [IN_PROGRESS]
Sprints 6-8 (M5)     : Spikes Execution (SPIKE-01..06), :docugraph-core & :docugraph-backend Implementation
Sprints 9-11(M6)     : :docugraph-mcp Server, :docugraph-app Compose UI, RevenueCat Integration
Sprint  12  (Release): End-to-End QA, Multiplatform Build Packaging, v1.0.0 Launch

5.4 Resource & Timeline Governance Protocols

1. Sprint Velocity Tracking: Bi-weekly tracking of WBS task completion against estimated person-days.
2. Definition of Done (DoD):
   • 100% unit and integration test pass rate for implemented module features.
   • Zero broken links or cyclic dependencies reported by validate_traceability.
   • Multiplatform build compilation success across Android, iOS, Desktop JVM, and Web targets.
3. Scope Management & Contingency Triggers: If implementation schedule slips by $>5$ working days, non-critical Pro visual canvas customization options will be deferred to post-v1.0.0 minor releases to preserve target launch dates.

---

6. TRACEABILITY INDEX

• Upstream Dependencies:
  • README.md (README)
  • AGENTS.md (AGENTS)
  • docs/00_BUSINESS_VISION.md (VISION-00)
  • docs/01_PROJECT_MANIFEST.md (MANIFEST-01)
  • docs/02_GLOBAL_SPEC.md (GLOBAL-02)
  • docs/03_ARCHITECTURE.md (ARCH-03)
  • docs/domain/01_DATABASE_SCHEMA.md (SCHEMA-01)
  • docs/domain/02_GLOSSARY.md (GLOSSARY-01)
  • docs/srs/SRS_IEEE-830.md (SRS-830)
• Downstream Artifacts:
  • docs/testing/TEST-01_verification-plan.md (TEST-01)