How Modules Are Organized in the src Directory of codebase-memory-mcp

The src directory follows a feature-oriented architecture that separates pure utilities (src/lib/), data-fetching hooks (src/hooks/), reusable UI primitives (src/components/ui/), and feature-specific components into distinct subdirectories, with application entry points at main.tsx and App.tsx.

The Graph UI front-end of the codebase-memory-mcp repository lives entirely within the src folder. This structure deliberately isolates side-effect-free logic from React-specific code, creating a modular foundation for the interactive 3-D graph visualization interface.

Root Application Files: App.tsx and main.tsx

The entry point src/main.tsx bootstraps the React tree and mounts the application to the DOM.

// src/main.tsx
import React from "react";
import { createRoot } from "react-dom/client";
import App from "./App";

createRoot(document.getElementById("root")!).render(<App />);

src/App.tsx serves as the root component that assembles the top-level layout—including the sidebar and tab bar—and provides global context providers used throughout the UI. This file acts as the orchestration layer that wires together the hooks, components, and styling defined in the subdirectories.

Library Layer: Pure Utilities in src/lib/

The src/lib/ directory contains pure TypeScript code with no side effects or React dependencies. These modules are import-only utilities that are easy to test and reuse across the application.

Type Definitions

src/lib/types.ts centralizes interface definitions for the graph data model, including GraphNode and GraphEdge structures used by hooks and components.

// src/lib/types.ts (excerpt)
export interface GraphNode {
  id: number;
  x: number;
  y: number;
  z: number;
  label: string;
  name: string;
  // …
}

Helper Functions

src/lib/utils.ts exports the cn function, a Tailwind class-merger that combines clsx and tailwind-merge for conditional styling.

// src/lib/utils.ts
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Additional files like i18n.ts, density.ts, and colors.ts handle localization, graph density calculations, and color palette definitions respectively.

Data Hooks: State Management in src/hooks/

Custom React hooks in src/hooks/ encapsulate data fetching, caching, and state-management logic. These hooks consume the back-end RPC API and return strongly-typed objects defined in src/lib/types.ts.

• useProjects.ts – Retrieves the list of indexed projects and caches the result.
• useGraphData.ts – Pulls the graph nodes and edges for a selected project, exposing loading and error states to the UI.

Both hooks abstract the complexity of the RPC layer, enabling type-safe components that consume clean data shapes.

Component Hierarchy: The src/components/ Directory

The src/components/ directory is split into two logical groups to separate generic UI primitives from domain-specific features.

UI Primitives

The src/components/ui/ subdirectory contains tiny, reusable components that wrap basic HTML elements with Tailwind styling. These are the building blocks of the interface.

// src/components/ui/button.tsx
import { cn } from "../../lib/utils";

export const Button = ({ className, ...props }) => (
  <button className={cn("rounded px-3 py-1", className)} {...props} />
);

Feature-Specific Components

The root of src/components/ houses higher-level UI pieces that assemble primitives into functional panels:

• GraphTab.tsx – The main view that renders the interactive 3-D graph by delegating to GraphScene and consuming data from useGraphData.
• Sidebar.tsx – Hosts the project selector and navigation tabs.
• NodeDetailPanel.tsx – Displays detailed information for selected graph nodes.

// src/components/GraphTab.tsx (excerpt)
import { useGraphData } from "../hooks/useGraphData";
import { GraphScene } from "./GraphScene";

export const GraphTab = () => {
  const { data, isLoading, error } = useGraphData();
  if (isLoading) return <Spinner />;
  if (error) return <ErrorMessage error={error} />;
  return <GraphScene graph={data?.graph} />;
};

API Layer: Backend Communication in src/api/

The src/api/ directory contains a thin wrapper around the back-end RPC layer. The src/api/rpc.ts file implements a JSON-RPC client that abstracts HTTP details, allowing hooks to remain focused on data shaping rather than transport concerns.

// src/api/rpc.ts (excerpt)
export async function call<T>(method: string, params?: unknown): Promise<T> {
  const response = await fetch("/api/rpc", {
    method: "POST",
    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params })
  });
  const { result } = await response.json();
  return result as T;
}

Global Styling in src/styles/

The src/styles/ directory contains globals.css, which defines custom CSS rules (such as scrollbar styling) to supplement the Tailwind utility classes applied throughout the component tree. Most styling is handled via Tailwind, keeping the stylesheet minimal.

Additionally, src/vite-env.d.ts provides TypeScript declarations for Vite's environment variables, ensuring type safety for build-time configuration.

Summary

• src/main.tsx and src/App.tsx serve as the application entry point and root layout orchestrator.
• src/lib/ houses pure TypeScript utilities and central type definitions (types.ts, utils.ts) with zero side effects.
• src/hooks/ encapsulates data fetching and caching logic (useGraphData.ts, useProjects.ts) for clean component consumption.
• src/components/ separates tiny reusable primitives (ui/) from feature-specific views (GraphTab.tsx, Sidebar.tsx).
• src/api/rpc.ts provides a thin JSON-RPC client abstraction for back-end communication.
• src/styles/ contains minimal global CSS to augment Tailwind's utility-first approach.

Frequently Asked Questions

What is the purpose of the src/lib/ directory?

The src/lib/ directory contains pure TypeScript modules that have no React dependencies or side effects. It houses shared type definitions (types.ts), styling utilities (utils.ts with the cn function), and helpers for localization and color management. This separation ensures that business logic and data shapes can be tested independently of the UI framework.

How does the src/components/ directory separate concerns?

The src/components/ directory uses a two-tier hierarchy: the ui/ subdirectory contains generic, reusable primitives like buttons and badges, while the root level contains feature-specific components like GraphTab.tsx and Sidebar.tsx. This distinction prevents tight coupling between low-level design elements and high-level business logic, making the UI primitives portable across different views.

Where does data fetching logic live in the src directory?

All data fetching logic resides in src/hooks/, specifically within custom hooks like useGraphData.ts and useProjects.ts. These hooks consume the JSON-RPC client defined in src/api/rpc.ts, transform the raw responses using types from src/lib/types.ts, and expose loading, error, and data states to React components. This pattern centralizes asynchronous side effects away from presentational components.

How are TypeScript types shared across the src directory?

Type definitions are centralized in src/lib/types.ts, which exports interfaces like GraphNode and GraphEdge used by the hooks in src/hooks/ and components in src/components/. By importing types from this single source of truth, the codebase maintains consistency between the RPC API responses, hook return values, and component props throughout the src directory structure.

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