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

> Discover how the codebase-memory-mcp src directory organizes modules using a feature-oriented architecture separating utilities hooks components and more into distinct subdirectories.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: internals
- Published: 2026-07-14

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/main.tsx) and [`App.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.tsx) bootstraps the React tree and mounts the application to the DOM.

```tsx
// 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/lib/types.ts) centralizes interface definitions for the graph data model, including `GraphNode` and `GraphEdge` structures used by hooks and components.

```ts
// 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/lib/utils.ts) exports the `cn` function, a Tailwind class-merger that combines `clsx` and `tailwind-merge` for conditional styling.

```ts
// 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/i18n.ts), [`density.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/density.ts), and [`colors.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/lib/types.ts).

- **[`useProjects.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/useProjects.ts)** – Retrieves the list of indexed projects and caches the result.
- **[`useGraphData.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.

```tsx
// 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/GraphTab.tsx)** – The main view that renders the interactive 3-D graph by delegating to `GraphScene` and consuming data from `useGraphData`.
- **[`Sidebar.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/Sidebar.tsx)** – Hosts the project selector and navigation tabs.
- **[`NodeDetailPanel.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/NodeDetailPanel.tsx)** – Displays detailed information for selected graph nodes.

```tsx
// 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.

```ts
// 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/vite-env.d.ts) provides TypeScript declarations for Vite's environment variables, ensuring type safety for build-time configuration.

## Summary

- **[`src/main.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/main.tsx)** and **[`src/App.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/types.ts), [`utils.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/utils.ts)) with zero side effects.
- **`src/hooks/`** encapsulates data fetching and caching logic ([`useGraphData.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/useGraphData.ts), [`useProjects.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/useProjects.ts)) for clean component consumption.
- **`src/components/`** separates tiny reusable primitives (`ui/`) from feature-specific views ([`GraphTab.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/GraphTab.tsx), [`Sidebar.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/Sidebar.tsx)).
- **[`src/api/rpc.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/types.ts)), styling utilities ([`utils.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/GraphTab.tsx) and [`Sidebar.tsx`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/useGraphData.ts) and [`useProjects.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/useProjects.ts). These hooks consume the JSON-RPC client defined in [`src/api/rpc.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/api/rpc.ts), transform the raw responses using types from [`src/lib/types.ts`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.