# How the Local HTTP Backend in GitNexus Powers AI Chat for the Web UI

> Discover how the local HTTP backend in GitNexus uses Express and REST API to stream AI chat responses and execute graph queries against KuzuDB for a powerful web UI experience.

- Repository: [Abhigyan Patwari/GitNexus](https://github.com/abhigyanpatwari/GitNexus)
- Tags: internals
- Published: 2026-03-08

---

**The local HTTP backend in GitNexus is an Express-based server that exposes MCP over HTTP and REST API endpoints, enabling the browser-based web UI to stream AI chat responses while executing graph queries and hybrid searches against a local KuzuDB instance.**

GitNexus implements a **local HTTP backend** that serves as the critical bridge between the browser-based web UI and the heavy-weight graph indexing engine running on the developer's machine. This architecture allows the web UI to remain lightweight while providing full access to AI-driven chat capabilities powered by local repository data. The backend combines two distinct communication layers: a stateful **MCP over HTTP** transport for streaming tool calls and a **REST API** for stateless data operations.

## Architecture of the Local HTTP Backend

The GitNexus HTTP backend is built on Express and organizes functionality into two complementary layers that share a single `LocalBackend` instance containing the KuzuDB graph database.

### MCP over HTTP Layer

The **Model-Control-Protocol (MCP) over HTTP** layer handles stateful streaming sessions between the Large Language Model (LLM) and the server. Mounted at **`/api/mcp`** in [`gitnexus/src/server/mcp-http.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/server/mcp-http.ts), this layer creates a `StreamableHTTPServerTransport` for each client session.

Key implementation details include:

- **Session Management**: Each client receives a unique session ID, with idle sessions automatically evicted after 30 minutes
- **Shared State**: The `LocalBackend` instance maintains the KuzuDB graph connection shared across all sessions
- **Streaming Transport**: The `StreamableHTTPServerTransport` enables real-time tool call streaming from the LLM back to the server

### REST API Layer

The **REST API** provides stateless endpoints for graph queries, hybrid search, and file operations. Defined in [`gitnexus/src/server/api.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/server/api.ts), these endpoints use the same `LocalBackend` to answer tool calls without maintaining session state.

Available endpoints include:

- **`POST /api/query`**: Executes Cypher queries against the KuzuDB graph
- **`POST /api/search`**: Performs BM25 + semantic hybrid search across indexed repositories
- **`GET /api/file`**: Retrieves file contents for citation and context extraction

## How the Web UI Connects to the Local HTTP Backend

The GitNexus web UI runs entirely in the browser using a **WebWorker** architecture ([`gitnexus-web/src/workers/ingestion.worker.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/workers/ingestion.worker.ts)) to offload AI processing from the main thread.

### Initializing the Backend Agent

When a user opens the chat panel, the UI invokes `initializeBackendAgent` (lines 637-673 in the worker) to establish the connection to the local HTTP backend:

1. **Configuration**: Receives the HTTP base URL (`backendUrl`) and repository name
2. **Wrapper Construction**: Creates thin HTTP wrappers around the REST API:
   - `createHttpExecuteQuery` → POST `/api/query` (lines 75-88)
   - `createHttpHybridSearch` → POST `/api/search` (lines 97-119)
3. **Agent Creation**: Builds a `CodebaseContext` via Cypher queries and instantiates a `GraphRAGAgent` with the HTTP wrappers as tool callbacks

### Streaming Chat Messages

Once initialized, chat messages flow through `workerApi.chatStream` (lines 716-744):

1. The worker forwards the message history to the `currentAgent`
2. The agent's tool callbacks invoke the HTTP wrappers, contacting the Express server to execute graph queries or hybrid searches
3. Results stream back through `streamAgentResponse` and render in the Right-Panel chat UI ([`gitnexus-web/src/components/RightPanel.tsx`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/components/RightPanel.tsx))

## Code Implementation Examples

The following patterns demonstrate how the web UI integrates with the local HTTP backend:

```typescript
// Create HTTP-backed tool wrappers (worker side)
const executeQuery = createHttpExecuteQuery(backendUrl, repoName);
const hybridSearch = createHttpHybridSearch(backendUrl, repoName);

```

```typescript
// Initialize the backend-mode GraphRAG agent
await workerApi.initializeBackendAgent(
  providerConfig,          // e.g. { provider: 'openai', model: 'gpt-5.2-chat', apiKey: '…' }
  backendUrl,              // e.g. 'http://127.0.0.1:3000'
  repoName,                // repository identifier
  Array.from(fileContents.entries()), // file map needed for citations
  'my-project'             // optional display name
);

```

```typescript
// Send a chat message from the UI
await workerApi.chatStream(messages, chunk => {
  // `chunk` is streamed back from the LLM; render it in the UI
  addChatChunk(chunk);
});

```

## Summary

- The **local HTTP backend in GitNexus** combines an Express server with MCP over HTTP and REST API layers to bridge the browser UI with local graph infrastructure.
- **MCP over HTTP** (`/api/mcp`) manages stateful streaming sessions with 30-minute eviction, while the **REST API** (`/api/query`, `/api/search`) handles stateless data operations against KuzuDB.
- The **WebWorker architecture** keeps the UI responsive by offloading LLM agent initialization and chat streaming to a background worker that communicates via HTTP wrappers.
- All LLM-generated tool calls route through these HTTP endpoints, enabling the web UI to remain lightweight while accessing full repository intelligence.

## Frequently Asked Questions

### What is the purpose of the MCP over HTTP layer in GitNexus?

The MCP over HTTP layer provides a **stateful transport mechanism** for streaming tool calls between the LLM and the local backend. Mounted at `/api/mcp` in [`gitnexus/src/server/mcp-http.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/server/mcp-http.ts), it uses `StreamableHTTPServerTransport` to maintain persistent sessions with unique IDs, allowing real-time bidirectional communication while the REST API handles simple request-response operations.

### How does GitNexus handle session management for AI chat?

GitNexus implements **automatic session eviction** where idle MCP sessions are terminated after 30 minutes of inactivity. Each client connection receives a unique session ID upon establishing the MCP over HTTP transport, and the `LocalBackend` instance maintains shared graph state (KuzuDB) across all active sessions while the transport layer manages per-session streaming contexts.

### What endpoints does the REST API expose for the web UI?

The REST API in [`gitnexus/src/server/api.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/server/api.ts) exposes several critical endpoints including **`POST /api/query`** for Cypher graph queries, **`POST /api/search`** for BM25 plus semantic hybrid search, and **`GET /api/file`** for retrieving file contents. These stateless endpoints use the same `LocalBackend` instance as the MCP layer to execute tool calls without maintaining session state between requests.

### How does the WebWorker architecture benefit the GitNexus web UI?

The **WebWorker architecture** isolates CPU-intensive LLM processing and HTTP communication from the main browser thread, preventing UI freezing during chat operations. Implemented in [`gitnexus-web/src/workers/ingestion.worker.ts`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus-web/src/workers/ingestion.worker.ts), the worker handles agent initialization, streams chat responses via `workerApi.chatStream`, and manages HTTP wrappers that communicate with the local backend, allowing the main thread to focus on rendering the chat interface in [`RightPanel.tsx`](https://github.com/abhigyanpatwari/GitNexus/blob/main/RightPanel.tsx).