Sangeetha-Grantha

Metadata Value
Status Active
Version 1.1.0
Last Updated 2026-09-10
Author Sangeetha Grantha Team
Document Type Design reference

Feature: Graph Explorer

[!NOTE] Design/reference material: this page may include proposals or earlier implementation assumptions. Use current feature map for implemented behavior and current operating steps.

1. Executive Summary

The Graph Explorer provides a visual, interactive interface for administrators to explore and understand the rich network of relationships between musical entities in the Sangeetha Grantha database. This feature enables users to discover connections between Krithis, Composers, Ragas, Talas, Deities, Kshetras, and Tags through an intuitive graph visualization, making it easier to understand the interconnected nature of Carnatic music knowledge.

Key Objectives:

Technology Stack: PostgreSQL with Recursive CTEs (backend) + Cytoscape.js (frontend visualization)

2. Targeted User Personas

Primary Users: Administrators and content curators working with the Sangeetha Grantha database.

User Stories:

3. Functional Requirements

3.1 Visual Graph Representation (High Priority)

Requirement: Display musical entities as nodes and their relationships as edges in an interactive graph visualization.

Details:

3.2 Interactive Node Expansion (High Priority)

Requirement: Allow users to start from a single entity and progressively expand the graph to explore connected entities.

Details:

3.3 Entity Search and Selection (High Priority)

Requirement: Provide search functionality to find and select entities as starting points for graph exploration.

Details:

3.4 Filtering by Entity Type (Medium Priority)

Requirement: Allow users to filter the visible graph to show only specific entity types and their relationships.

Details:

3.5 Graph Navigation and Interaction (Medium Priority)

Requirement: Provide intuitive controls for navigating and interacting with the graph visualization.

Details:

3.6 Performance and Scalability (High Priority)

Requirement: Ensure the graph explorer performs efficiently even with large datasets.

Details:

4. Technical Approach

4.1 Architecture Overview

The implementation follows a “Client-Side Graph” model as documented in ADR-005:

┌─────────────────┐
│  Admin Web UI   │
│  (Cytoscape.js) │
└────────┬────────┘
         │ JSON Graph DTOs (Nodes/Edges)
┌────────▼────────┐
│  GraphService   │
│ (Ktor Backend)  │
└────────┬────────┘
         │ Recursive SQL
┌────────▼────────┐
│   PostgreSQL    │
└─────────────────┘

4.2 Backend Implementation

Database Strategy: Use PostgreSQL with Recursive Common Table Expressions (WITH RECURSIVE) to perform graph traversals. This approach was selected over Neo4j for operational simplicity, team familiarity, and cost efficiency (see ADR-005 for full rationale).

Query Strategy:

  1. Base Case: Select the starting entity (e.g., a specific Krithi by UUID).
  2. Recursive Step: Join with relationship tables (krithi_ragas, composers, krithi_talas, etc.) to find connected entities.
  3. Termination: Stop when depth reaches the requested limit (1-3).
  4. Result: Return distinct nodes and edges as JSON DTOs to the frontend.

API Endpoints:

4.3 Frontend Implementation

Visualization Library: Use Cytoscape.js for graph visualization (as per ADR-005 decision).

Key Components:

State Management:

4.4 Data Model

Graph DTOs:

interface GraphNode {
  id: string;        // UUID
  type: EntityType;  // 'Krithi' | 'Composer' | 'Raga' | 'Tala' | 'Deity' | 'Kshetram' | 'Tag'
  label: string;     // Display name
  metadata?: Record<string, any>; // Additional entity-specific data
}

interface GraphEdge {
  id: string;
  source: string;    // Source node UUID
  target: string;    // Target node UUID
  type: string;      // Relationship type (e.g., 'COMPOSED_BY', 'IN_RAGA')
  metadata?: Record<string, any>;
}

interface GraphResponse {
  nodes: GraphNode[];
  edges: GraphEdge[];
}

5. Success Metrics

6. Implementation Roadmap

7. References

Section index · Documentation home · Feature status