Backend Spec: Project Adjacency Graph Query Service (graph.build)

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.

Backend Spec: Project Adjacency Graph Query Service (graph.build)

1. Overview & Objectives

This specification details the server-side endpoint (buildGraph) for querying the full directed acyclic graph (DAG) structure of a registered project workspace. It processes HTTP GET /api/v1/projects/{id}/graph, performs authenticated project lookup, executes optimized SQL joins on nodes and node_edges, and returns a structured JSON graph payload for visualization in :docugraph-app.

2. API Endpoint Signature & Traceability

• HTTP Method & Path: GET /api/v1/projects/{id}/graph
• operationId: buildGraph
• Upstream Requirements: US-03, IX-03, SCHEMA-01
• Primary Service Class: GraphService.kt
• Ktor Route Handler: GraphRoutes.kt

3. Data Models & Kotlin Data Classes

package io.docugraph.backend.models.graph

import kotlinx.serialization.Serializable

@Serializable
data class GraphNodeDto(
    val id: String,
    val atomicId: String,
    val title: String,
    val documentType: String,
    val status: String,
    val relativeFilePath: String,
    val fileChecksumSha256: String,
    val frontmatterJson: Map<String, String> = emptyMap(),
    val tags: List<String> = emptyList()
)

@Serializable
data class GraphEdgeDto(
    val id: String,
    val sourceNodeId: String,
    val targetNodeId: String,
    val relationshipType: String // "depends_on" | "depended_by" | "related" | "tables"
)

@Serializable
data class GraphDataResponse(
    val projectId: String,
    val nodes: List<GraphNodeDto>,
    val edges: List<GraphEdgeDto>,
    val totalNodes: Int,
    val totalEdges: Int
)

4. Sequence & Control Flow

Client (FE-03)         Ktor GraphRoute         GraphService           PostgreSQL DB
      |                       |                      |                      |
      |-- GET /projects/{id}/graph ----------------->|                      |
      |                       |-- verify project --->|                      |
      |                       |   ownership          |-- SELECT FROM nodes->|
      |                       |                      |<- node list ---------|
      |                       |                      |                      |
      |                       |                      |-- SELECT node_edges->|
      |                       |                      |<- edge list ---------|
      |                       |                      |                      |
      |                       |                      |-- assemble DAG JSON->|
      |<- 200 GraphDataResp --|<- GraphDataResponse -|                      |

5. Database Interaction & SQL Queries

5.1 Fetch All Project Nodes

SELECT
    id,
    atomic_id,
    title,
    document_type,
    status,
    relative_file_path,
    file_checksum_sha256,
    frontmatter_json,
    tags
FROM nodes
WHERE project_id = :projectId
ORDER BY atomic_id ASC;

5.2 Fetch All Project Edges

SELECT
    id,
    source_node_id,
    target_node_id,
    relationship_type
FROM node_edges
WHERE project_id = :projectId;

6. Optimization & Caching Strategy

1. ETag & Checksum Validation:
   • Compute MD5/SHA256 checksum over the combined (node_count, edge_count, updated_at) of the target project.
   • Return HTTP 304 Not Modified if client header If-None-Match matches project checksum.
2. In-Memory Graph Cache:
   • Cache serialized GraphDataResponse in Guava/Caffeine cache keyed by projectId.
   • Invalidate cache automatically whenever createProject or workspace re-index completes.

7. Error Handling & HTTP Status Codes

Error Condition	HTTP Code	Internal Code	Response Message
Invalid UUID path format	400 Bad Request	INVALID_PROJECT_ID	“Project ID must be a valid UUID.”
Project not found or owned by another user	404 Not Found	PROJECT_NOT_FOUND	“Project with given ID was not found.”
Database connection failure	500 Server Error	DATABASE_ERROR	“Failed to fetch project graph nodes.”

8. Verification & Test Plan

• Unit Test: Test graph serialization with various node/edge combinations.
• Integration Test: Query Ktor endpoint for newly indexed project and assert exact node and edge count matches DB.