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
- 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
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)
| 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)
| # | 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
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
- 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