How the Code‑Review‑Graph Registry Manages Multiple Repositories in VS Code

The registry uses a SQLite‑backed UUID system with per‑repository data isolation to enable concurrent tracking of unlimited codebases without collisions.

The tirth8205/code‑review‑graph extension tracks Git repositories through a central registry component that handles registration, persistence, and isolation. This architecture ensures that whether you open one workspace or fifty, each repository’s graph data remains separate while sharing a single lightweight database file.

SQLite‑Based Repository Registry

The registry persists all data in a lightweight SQLite database defined in src/backend/sqlite.ts. This single source of truth eliminates file‑system clutter and provides ACID guarantees for concurrent operations.

The repositories Table Schema

The database contains a repositories table that establishes the identity for every tracked codebase. When a repository is first registered, the system generates a unique UUID that serves as the immutable identifier for that workspace.

Each row stores:

• UUID – The primary key generated on first registration.
• Absolute path – The root directory of the Git repository.
• Auxiliary metadata – Remote URL, default branch, and other configuration details.

This schema ensures that moving or renaming a repository on disk does not create duplicate entries as long as the path remains consistent.

Registration and Deregistration Workflow

The extension automatically detects Git workspaces and syncs them with the registry through an asynchronous API.

Automatic Detection via the File Watcher

When a user opens a folder in VS Code, the watcher (src/backend/watcher.ts) detects the Git root and triggers the registration flow. This background process requires no manual intervention.

The watcher calls the core registry API to register the detected path:

import { Registry } from './backend/registry';

async function onWorkspaceOpened(rootPath: string) {
  const repoId = await Registry.registerRepository(rootPath);
  console.log(`Repository registered with id ${repoId}`);
}

If the repository already exists in the database (same absolute path), registerRepository returns the existing UUID rather than creating a duplicate entry.

The registerRepository API

The Registry class exported from src/backend/registry.ts exposes idempotent registration methods. The function signature accepts a repository root path and returns a Promise that resolves to the stable UUID:

const repoId = await registry.registerRepository(repoRootPath);

This design lets multiple VS Code windows or background jobs safely call registration simultaneously without race conditions.

Repository Isolation and Concurrent Access

Data integrity across multiple repositories relies on strict UUID scoping and SQLite’s built‑in concurrency controls.

UUID‑Based Data Scoping

All graph‑related tables—including nodes, edges, and code‑review metadata—use the repository UUID as a foreign key. Queries always filter by this identifier, guaranteeing that data from one repository never leaks into another.

To retrieve isolated graph data, use the GraphStore methods from src/backend/sqlite.ts:

import { GraphStore } from './backend/sqlite';

async function getRepoGraph(repoId: string) {
  const nodes = await GraphStore.getNodesForRepo(repoId);
  const edges = await GraphStore.getEdgesForRepo(repoId);
  return { nodes, edges };
}

Safe Concurrent Operations

The SQLite connection opens in read‑write mode with proper file‑level locking. Because the registry’s methods are asynchronous and return Promises, the UI remains responsive while database operations execute in the background. This architecture supports dozens or hundreds of repositories because the SQLite file is designed for concurrent reads and writes across multiple extension instances.

Cleanup and Deregistration

When a workspace closes, the watcher informs the registry to remove the active reference. This deregistration updates the registry state without necessarily deleting historical graph data (which can be pruned later via background jobs):

async function onWorkspaceClosed(rootPath: string) {
  await Registry.deregisterRepository(rootPath);
  console.log(`Repository at ${rootPath} removed from the registry`);
}

Summary

• UUID Identity: Every repository receives a stable UUID stored in src/backend/sqlite.ts, preventing duplicates and enabling persistent references.
• Automatic Registration: The file watcher in src/backend/watcher.ts detects Git roots and invokes Registry.registerRepository() from src/backend/registry.ts without user intervention.
• Data Isolation: Foreign key relationships in the SQLite schema ensure graph nodes and edges remain scoped to their respective repositories.
• Concurrency Safe: SQLite’s locking mechanism and async Promise-based APIs allow multiple VS Code windows to interact with the registry simultaneously.

Frequently Asked Questions

How does the registry prevent duplicate repository entries?

The registerRepository method in src/backend/registry.ts checks the absolute path against the repositories table. If a matching entry exists, it returns the existing UUID instead of generating a new one, making registration idempotent.

Can multiple VS Code windows access the registry simultaneously?

Yes. The SQLite database opens in read‑write mode with file‑level locking enabled. Since all registry methods return Promises and execute asynchronously, concurrent calls from different windows or background threads are processed safely without corruption.

What happens to graph data when a repository is deregistered?

Deregistration removes the repository’s UUID reference from the active registry but does not immediately delete the underlying nodes and edges. This allows for data archival or later re‑attachment, with optional pruning handled by background maintenance jobs.

Where is the registry data physically stored?

The registry persists data in a SQLite database file managed by the GraphStore class in src/backend/sqlite.ts. The database location is typically within the extension’s global storage path, ensuring it persists across VS Code sessions while remaining isolated from the workspace directories.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}