Section 1.2Source: server/src/routes/repository.routes.ts

Getting Started

Learn how a codebase enters the CodeGraph pipeline, how the backend parses and indexes the graph, and how to query repository metrics.

Source: server/src/routes/repository.routes.ts

1. Ingesting a Repository

Repositories enter the CodeGraph platform via the REST API or Dashboard. When you submit a repository URL or directory path, the backend clones or resolves the repository and initiates the pipeline:

POST /api/repositories

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Request Body
{
  "url": "https://github.com/facebook/react"
}

// Response: 201 Created
{
  "success": true,
  "message": "Repository created successfully",
  "data": {
    "_id": "65fc9a1e0b12a84d",
    "name": "react",
    "status": "completed",
    "createdAt": "2026-09-17T12:00:00.000Z"
  }
}

2. Retrieving the Graph & Overview

Once the status is completed, the entire canonical graph and high-level architectural statistics are available for querying:

GET /api/repositories/:id/overview

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "success": true,
  "data": {
    "statistics": {
      "fileCount": 142,
      "symbolCount": 864,
      "relationshipCount": 1892,
      "dependencyCount": 18,
      "moduleCount": 6
    },
    "health": {
      "index": 84.6,
      "metrics": {
        "cycles": { "score": 99.6, "cycleCount": 1 },
        "coupling": { "score": 90.9, "averageStructuralDegree": 1.88 },
        "fanOut": { "score": 66.8, "rootMeanSquareFanOut": 0.99 },
        "fanIn": { "score": 85.3, "rootMeanSquareFanIn": 0.34 },
        "dependency": { "score": 65.2, "averageDependenciesPerFile": 1.07 },
        "modules": { "score": 99.9, "moduleRatio": 0.00069 }
      }
    }
  }
}

3. Querying Graph Analytics

You can run granular algorithmic queries directly against any node ID in the graph:

Endpoint	Algorithm / Query	Purpose
GET /api/analytics/:id/analysis/impact?sourceNodeId=...	Backward BFS Traversal	Calculates all upstream files and symbols impacted by a change.
GET /api/analytics/:id/analysis/dependencies?sourceNodeId=...	Forward BFS Traversal	Discovers transitive downstream dependencies with hop depth.
GET /api/analytics/:id/analysis/cycles	Tarjan's SCC Algorithm	Detects circular imports and mutual function recursion across 5 projections.
GET /api/analytics/:id/analysis/ordering?sourceNodeId=...	Kahn's Topological Sort	Produces a safe linear initialization sequence for symbols.
GET /api/analytics/:id/analysis/paths?sourceNodeId=...&targetNodeId=...	Iterative DFS with Backtracking	Finds the exact point-to-point call chain between two functions.

Next Steps

To understand the internal pipeline stages that transform code on disk into this queryable graph, proceed to Section 2.1: System Overview.

1.1 What is CodeGraph?

2.1 System Overview