DocuGraph Monorepo Overview

DocuGraph

DocuGraph: Núcleo de documentación atómica, grafo de dependencias y servidor MCP en Kotlin para desarrollo asistido por IA.

Naturaleza (Shipaton 2026): investigación y validación técnica. Documento gobernante: docs/00_MASTER_CONTEXT.md (MASTER-00). Plan de investigación: research/00_RESEARCH_PLAN.md.

DocuGraph convierte la documentación de un proyecto de software en un grafo vivo de nodos atómicos conectados por IDs. El núcleo y el servidor MCP, implementados en Kotlin, entregan a agentes de IA (como Claude Code, Cursor, Junie y GitHub Copilot) solo el contexto necesario para implementar una tarea específica. La lectura y edición humana se realizan sobre Markdown con Obsidian o Gitea; el visor web ofrece una superficie adicional de solo lectura.

El proyecto se trata inicialmente como investigación y validación técnica, no como producto comprometido: las hipótesis (H01–H14) y métricas se gestionan en research/. El perfil operativo vigente es self-hosted y gratuito: Markdown + Git, MCP, Obsidian, Gitea y visor web. La antigua app Compose Mobile/Desktop permanece solo en la documentación histórica del catálogo.

🚀 Requisitos Previos

JDK: OpenJDK 17 o superior.
Gradle: 8.x (utiliza el wrapper incluido ./gradlew).
IDE: IntelliJ IDEA u otro editor compatible (opcional; el flujo principal usa terminal y Markdown).
Kotlin: 2.4.10

🛠️ Instalación y Configuración

# Clone repository
git clone https://github.com/docugraph/docugraph.git
cd docugraph

# Build the project and run tests
./gradlew build test

# Run MCP Server locally (STDIO transport)
./gradlew :docugraph-mcp:run

📋 Variables de Entorno (`.env`)

Crea un archivo .env en la raíz del proyecto basándote en la siguiente plantilla:

# MCP Server Settings
MCP_SERVER_PORT=8080
MCP_ALLOWED_ROOTS=/home/machaca/Documentos/Github/docugraph

📖 Estructura de Documentación Atómica

Este proyecto utiliza el estándar de Documentación Atómica. Toda la especificación vive dentro del directorio docs/:

docs/00_MASTER_CONTEXT.md: Documento Maestro de contexto/gobernanza (MASTER-00, v0.01) — perfil self-hosted vigente y catálogo histórico de fases anteriores.
research/00_RESEARCH_PLAN.md: Preguntas (RQ01–12), hipótesis (H01–14), métricas, experimentos y registro de decisiones.
docs/00_BUSINESS_VISION.md: Visión de negocio, actores y reglas globales (propuesta).
docs/01_PROJECT_MANIFEST.md: Matriz de trazabilidad, estado de tareas y clasificación por fases (MANIFEST-01).
docs/02_GLOBAL_SPEC.md: Especificación global, propósito y límites de alcance.
docs/03_ARCHITECTURE.md: Arquitectura de software, diagramas y componentes.
docs/domain/: Modelo de base de datos y glosario de términos.
docs/user_stories/: Historias de usuario (US-XX).
docs/interaction/: Specs de diseño de interacción (IX-XX).
docs/api/openapi.yaml: Contrato único OpenAPI (fuente de verdad).
docs/backend/: Specs de tareas backend (BE-XX).
docs/frontend/: Especificaciones frontend históricas (FE-XX), sin módulo de aplicación activo.
docs/mcp/: Especificación técnica del Servidor MCP.

Contratos MCP de contexto e inventario

get_task_context usa contentMode=summary por defecto para devolver metadata, relaciones y el informe de inclusión sin repetir cuerpos Markdown. Los clientes que necesiten el formato completo deben solicitar contentMode=full; ambos modos aceptan maxTokens, una estimación orientativa de caracteres/4 que recorta cuerpos de forma determinista y declara truncated/truncationReason. En full, prioriza secciones completas delimitadas por encabezados ## o inferiores; solo una sección individual demasiado grande usa el fallback por caracteres y la marca [truncated: maxTokens].

list_tasks devuelve workspacePath, los filters recibidos, documentCount, taskCount y la lista filtrada. includeDocuments=true añade solo metadata ligera (id, path, title, type, status, phase y enlaces); reconoce backend_task, backend_task_spec, frontend_task, frontend_task_spec, frontend_component_spec, user_story, interaction y design. Una lista tasks=[] significa que no hubo coincidencias, no que el workspace esté vacío: documentCount y taskCount muestran si se trata de un inventario sin tareas o de un filtro sin coincidencias.

lint_workspace es un diagnóstico read-only con perfiles advisory y strict: devuelve el ValidationReport estructural por separado de advisories de convención y siempre declara mutated=false. valid=true y Tarjan cubren únicamente frontmatter, enlaces, asimetrías y ciclos; no prueban coherencia semántica, calidad de requisitos ni conveniencia conceptual de dependencias.

Los documentos Markdown conservan frontmatter con id, title, type, status, tags y links; los IDs atómicos y sus enlaces DAG son la referencia de trazabilidad. En instalaciones con varios proyectos, .docugraph/project.yaml aporta el projectSlug seguro para resolver projects/<projectSlug>; /workspace es un alias de despliegue y workspacePath devuelve la raíz canónica real (por ejemplo, C:\... en Windows). La caché comprueba al consultar la huella de Markdown y no promete notificaciones en tiempo real; no se aceptan rutas arbitrarias ni correcciones automáticas desde lint.

Repositorio documental central

El motor de DocuGraph y el workspace documental son repositorios separados. El workspace central es cleverjohann/docugraph-workspace: contiene docs/, research/ y la configuración del visor, mientras este repositorio conserva el código Kotlin, las pruebas y el despliegue. Cada proyecto vive bajo projects/<slug>/; no se crea un repositorio por proyecto ni por Markdown.

Workspace operativo

El despliegue self-hosted usa un checkout Git separado del repositorio documental central, explícitamente reducido a README.md, AGENTS.md, PROJECT.md, mkdocs.yml, javascripts/, docs/, research/ y projects/** mediante Git sparse-checkout. El MCP carga un solo projects/<slug> por solicitud; el modo legado, sin carpeta projects/, sigue disponible para migraciones graduales.