Saltar a contenido

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:
  2. Compute MD5/SHA256 checksum over the combined (node_count, edge_count, updated_at) of the target project.
  3. Return HTTP 304 Not Modified if client header If-None-Match matches project checksum.
  4. In-Memory Graph Cache:
  5. Cache serialized GraphDataResponse in Guava/Caffeine cache keyed by projectId.
  6. 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.