DocuGraph Project Overview
Project: DocuGraph
Sección titulada «Project: DocuGraph»Gobernanza: investigación y validación técnica reorientada al perfil self-hosted gratuito. Documento gobernante: docs/00_MASTER_CONTEXT.md (
MASTER-00, v0.01). La operación vigente usadocugraph-core,docugraph-mcp, Markdown + Git, Obsidian, Gitea y el visor web. La antigua app Compose y el backend relacional permanecen únicamente como catálogo histórico.
Architecture
Sección titulada «Architecture»- Product Overview: Herramienta personal self-hosted de documentación atómica, grafo de dependencias y contexto MCP.
- Core Library (
:docugraph-core): Biblioteca Kotlin que proporciona parsing de frontmatter, modelo de grafo, validación DAG, orden topológico, detección de ciclos y verificación de enlaces. - MCP Server (
:docugraph-mcp): Servidor Kotlin MCP que expone recursos, tools y prompts mediante STDIO y HTTP remoto. - Reading surfaces: Obsidian sobre el clon Git, Gitea para revisión web puntual y MkDocs para navegación web de solo lectura.
- Legacy catalog: Las especificaciones de aplicación, backend relacional y RevenueCat se conservan para trazabilidad histórica, pero no forman parte de la implementación vigente.
Feature Inventory
Sección titulada «Feature Inventory»Every target documentation artifact is inventoried below and mapped to its assigned milestone.
| # | Feature | Target File Path | Description | Milestone | Source |
|---|---|---|---|---|---|
| 1 | README | README.md |
Project overview, quickstart, architecture summary, atomic documentation principles | M1 | Survey |
| 2 | AGENTS | AGENTS.md |
Guidelines for AI agents interacting with DocuGraph codebase and MCP server | M1 | Survey |
| 3 | Business Vision | docs/00_BUSINESS_VISION.md |
Product vision, target developer/architect audience, problem statement, solution, RevenueCat freemium model | M1 | Survey |
| 4 | US-01 Login | docs/user_stories/US-01_login.md |
User Story: Authentication and session management | M1 | Survey |
| 5 | US-02 Create Project | docs/user_stories/US-02_create_project.md |
User Story: Project creation, git repo link, YAML schema setup | M1 | Survey |
| 6 | US-03 View Graph | docs/user_stories/US-03_view_graph.md |
User Story: Interactive node-edge graph visualization and filtering | M1 | Survey |
| 7 | US-04 Get Task Context | docs/user_stories/US-04_get_task_context.md |
User Story: MCP context bundle extraction for AI task implementation | M1 | Survey |
| 8 | US-05 Validate Traceability | docs/user_stories/US-05_validate_traceability.md |
User Story: Automated graph integrity and cross-reference validation | M1 | Survey |
| 9 | US-06 RevenueCat Pro | docs/user_stories/US-06_revenuecat_pro.md |
User Story: Paywall, subscription management, Pro features entitlement | M1 | Survey |
| 10 | Project Manifest | docs/01_PROJECT_MANIFEST.md |
Central manifest & 100% end-to-end traceability matrix | M2 | Survey |
| 11 | Global Spec | docs/02_GLOBAL_SPEC.md |
Scope boundaries (what it does / DOES NOT do), stack, core principles | M2 | Survey |
| 12 | Architecture Spec | docs/03_ARCHITECTURE.md |
System design, KMP core, Compose UI, Kotlin MCP Server, DB schema, data flow | M2 | Survey |
| 13 | Database Schema | docs/domain/01_DATABASE_SCHEMA.md |
6 relational tables (users, subscriptions, projects, nodes, node_edges, mcp_api_keys) |
M2 | Survey |
| 14 | Domain Glossary | docs/domain/02_GLOSSARY.md |
Terms, definitions, atomic documentation taxonomy | M2 | Survey |
| 15 | IX-01 Login Flow | docs/interaction/IX-01_login-flow.md |
Interaction Spec: User authentication, JWT storage, error handling | M2 | Survey |
| 16 | IX-02 Create Project Flow | docs/interaction/IX-02_create-edit-project-flow.md |
Interaction Spec: Project creation, frontmatter parsing, validation | M2 | Survey |
| 17 | IX-03 Graph Inspection Flow | docs/interaction/IX-03_graph-inspection-flow.md |
Interaction Spec: Node selection, canvas pan/zoom, detail panel | M2 | Survey |
| 18 | IX-04 MCP Context Bundle Flow | docs/interaction/IX-04_mcp-context-bundle-flow.md |
Interaction Spec: AI agent querying MCP server for context bundle | M2 | Survey |
| 19 | OpenAPI Spec | docs/api/openapi.yaml |
OpenAPI 3.1.0 contract (single source of truth with 6 operationIds) | M3 | Survey |
| 20 | BE-01 Auth Login | docs/backend/BE-01_auth-login.md |
Backend Spec: POST /api/v1/auth/login (loginUser) |
M3 | Survey |
| 21 | BE-02 Project Create | docs/backend/BE-02_project-create.md |
Backend Spec: POST /api/v1/projects (createProject) |
M3 | Survey |
| 22 | BE-03 Graph Build | docs/backend/BE-03_graph-build.md |
Backend Spec: GET /api/v1/projects/{id}/graph (buildGraph) |
M3 | Survey |
| 23 | BE-04 MCP Task Context | docs/backend/BE-04_mcp-get-task-context.md |
Backend Spec: POST /api/v1/mcp/task-context (getTaskContext) |
M3 | Survey |
| 24 | BE-05 MCP Validate | docs/backend/BE-05_mcp-validate-traceability.md |
Backend Spec: POST /api/v1/mcp/validate-traceability (validateTraceability) |
M3 | Survey |
| 25 | BE-06 Paywall Check | docs/backend/BE-06_paywall-check-entitlement.md |
Backend Spec: GET /api/v1/subscriptions/entitlement (checkEntitlement) |
M3 | Survey |
| 26 | FE-01 LoginForm | docs/frontend/FE-01_login-form.md |
Frontend Spec: Compose LoginForm component, state, validation | M3 | Survey |
| 27 | FE-02 ProjectDashboard | docs/frontend/FE-02_project-dashboard.md |
Frontend Spec: Compose ProjectDashboard component, project list, actions | M3 | Survey |
| 28 | FE-03 GraphCanvas | docs/frontend/FE-03_graph-canvas.md |
Frontend Spec: Compose GraphCanvas interactive node/edge canvas | M3 | Survey |
| 29 | FE-04 NodeInspector | docs/frontend/FE-04_node-inspector.md |
Frontend Spec: Compose NodeInspector detail drawer, editor, links | M3 | Survey |
| 30 | FE-05 PaywallModal | docs/frontend/FE-05_paywall-modal.md |
Frontend Spec: Compose PaywallModal RevenueCat Pro subscription UI | M3 | Survey |
| 31 | MCP Specification | docs/mcp/MCP_SPEC.md |
Kotlin MCP Server Spec: Resources, Tools, Prompts, Transports, Auth | M3 | Survey |
| 32 | SRS IEEE 830 | docs/srs/SRS_IEEE-830.md |
Software Requirements Specification IEEE 830 compliant document | M4 | Survey |
| 33 | Project Plan | docs/project_plan/PLAN-01_delivery-plan.md |
Implementation plan, technical spikes, milestones, risk matrix | M4 | Survey |
| 34 | Test Plan | docs/testing/TEST-01_verification-plan.md |
Test strategy, unit/integration/E2E fixtures, verification matrix | M4 | Survey |
La columna Milestone (M1–M4) indica la fase de autoría del artefacto dentro del catálogo. La fase de alcance de cada artefacto se declara en su frontmatter (
phase: GATE_0 | POC | MVP | POST_MVP) según §5/§6 de MASTER-00; el mapa completo está enMANIFEST-01§4.5.
Delivery Gates (MASTER-00 §5)
Sección titulada «Delivery Gates (MASTER-00 §5)»| Gate | Objetivo | Cierre | Estado |
|---|---|---|---|
| Gate 0 | Viabilidad técnica del servidor MCP | get_task_context + validate_traceability sobre repo demo + ejecución de EXP-01 |
BACKLOG |
| PoC | Validación cuantitativa del contexto | 3 tareas, gold standard, métricas e informe | BACKLOG |
| Gate de integración de app | Decidir Plan A (live) vs Plan B (precalculado) | Veredicto honesto | APROBADO — Plan B (DEC-009, research/99_DECISION_LOG.md) |
| MVP Shipaton | Comunicar y monetizar lo validado | 12 pantallas en 5 flujos + RevenueCat esencial (Mobile) | BACKLOG |
| Fase D — Desktop | Entorno operativo principal sobre el núcleo compartido | Repositorios locales, MCP, edición, bundles reales, verificación Pro | BACKLOG |
| Fase E — Conexión | Sincronización/emparejamiento entre dispositivos solo con evidencia | Decisión previa obligatoria (§5.6) | BACKLOG |
| Producto | Catálogo completo de experiencia | Post-MVP sujeto a validación | BACKLOG |
Ninguna fase se implementa sin aprobar su gate (§15 de MASTER-00). El proyecto se trata inicialmente como investigación; la prioridad es demostrar que el contexto recuperado por dependencias conserva lo obligatorio, reduce lo irrelevante y justifica el mantenimiento del grafo.
Milestones (historia de autoría del catálogo)
Sección titulada «Milestones (historia de autoría del catálogo)»| # | Name | Scope | Dependencies | Status |
|---|---|---|---|---|
| M1 | Foundation & User Stories | README.md, AGENTS.md, docs/00_BUSINESS_VISION.md, US-01 to US-06 (9 files) |
None | DONE |
| M2 | System Manifest, Domain & Interaction Specs | 01_PROJECT_MANIFEST.md, 02_GLOBAL_SPEC.md, 03_ARCHITECTURE.md, 01_DATABASE_SCHEMA.md, 02_GLOSSARY.md, IX-01 to IX-04 (9 files) |
M1 | DONE |
| M3 | OpenAPI Contract, Backend, Frontend & MCP Specs | openapi.yaml, BE-01..BE-06, FE-01..FE-05, MCP_SPEC.md (13 files) |
M2 | DONE |
| M4 | SRS IEEE 830, Project Plan & Test Plan | SRS_IEEE-830.md, PLAN-01_delivery-plan.md, TEST-01_verification-plan.md (3 files) & Final Verification |
M3 | IN_PROGRESS |
Interface Contracts
Sección titulada «Interface Contracts»Client / Server & MCP API
Sección titulada «Client / Server & MCP API»- Protocol: HTTP REST (OpenAPI 3.1.0) & MCP JSON-RPC 2.0 (Stdio / SSE)
- Base Path:
/api/v1 - Operation IDs:
loginUser,createProject,buildGraph,getTaskContext,validateTraceability,checkEntitlement - MCP Tools:
get_task_context,get_dependency_graph,validate_traceability - Data Formats:
application/json,application/yaml,text/markdownwith YAML Frontmatter
Alcance Gate 0 (MASTER-00 §5.1): solo
get_task_contextyvalidate_traceabilityen transporteSTDIO.get_dependency_graph, SSE, backend REST y PostgreSQL pertenecen a PoC/Producto (POST_MVP). Cloud: no requerido inicialmente (§7).
Code Layout
Sección titulada «Code Layout»- Root documentation:
README.md,AGENTS.md,PROJECT.md - Operational documentation:
docs/, published through MkDocs from the selected workspace - Active implementation:
docugraph-core/,docugraph-mcp/ - Self-hosted deployment:
deploy/oracle/,deploy/viewer/, andscripts/ - Research and evidence:
research/, excluded from the operational checkout and public graph