# Pi-web Directory Structure: Complete Guide to the Next.js TypeScript Layout

> Explore the Pi-web Next.js TypeScript directory structure. Understand the app/, components/, lib/, docs/, and bin/ folders for efficient development. Your complete guide.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: internals
- Published: 2026-07-27

---

**Pi-web organizes its codebase into five primary directories—`app/`, `components/`, `lib/`, `docs/`, and `bin/`—following standard Next.js conventions with TypeScript throughout.**

Pi-web is a Next.js application that separates frontend UI, backend API logic, and core libraries into distinct, clearly defined folders. Understanding the **Pi-web directory structure** is essential for navigating the agent-client functionality, extending the chat interface, or contributing to the worktree management features. The repository maintains a flat hierarchy where test files co-locate with their source modules, and all business logic lives in the `lib/` folder consumed by both server and client code.

## Top-Level Directory Overview

The repository root contains standard configuration files alongside five functional directories that handle specific architectural concerns:

- **`app/`** – Next.js pages, root layout, global styles, and the entry point component
- **`components/`** – Reusable React UI pieces including chat windows, sidebars, and file explorers
- **`lib/`** – Core TypeScript libraries powering server-side operations like agent communication and file access
- **`docs/`** – Markdown documentation, release notes, and technical guides
- **`bin/`** – Small CLI utilities for development workflows and worktree management

Configuration files at the root include [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json), [`tsconfig.json`](https://github.com/agegr/pi-web/blob/main/tsconfig.json), [`next.config.ts`](https://github.com/agegr/pi-web/blob/main/next.config.ts), [`tailwind.config.ts`](https://github.com/agegr/pi-web/blob/main/tailwind.config.ts), and ESLint configurations. Test files use the `.test.mjs` extension and sit alongside the modules they validate, such as `lib/file-access.test.mjs` adjacent to [`lib/file-access.ts`](https://github.com/agegr/pi-web/blob/main/lib/file-access.ts).

## Frontend Architecture: The app/ and components/ Directories

### Next.js Pages and Layouts in app/

The **`app/`** directory contains the Next.js App Router structure. The file [`app/page.tsx`](https://github.com/agegr/pi-web/blob/main/app/page.tsx) serves as the root page component and entry point for the UI, while [`app/layout.tsx`](https://github.com/agegr/pi-web/blob/main/app/layout.tsx) provides the global shell that wraps all pages. Global CSS variables and Tailwind directives live in [`app/globals.css`](https://github.com/agegr/pi-web/blob/main/app/globals.css), and static assets like `favicon.ico` reside here as well.

### Reusable React Components in components/

The **`components/`** folder houses all React UI elements that render the chat interface and file management views. Key files include:

- **[`components/ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/components/ChatWindow.tsx)** – Core chat interface handling streaming responses and server-sent events
- **[`components/SessionSidebar.tsx`](https://github.com/agegr/pi-web/blob/main/components/SessionSidebar.tsx)** – Displays the session tree and file explorer navigation
- **[`components/FileExplorer.tsx`](https://github.com/agegr/pi-web/blob/main/components/FileExplorer.tsx)** – Renders the repository file tree and worktree browser
- **[`components/AppShell.tsx`](https://github.com/agegr/pi-web/blob/main/components/AppShell.tsx)** – Provides the main application layout container
- **[`components/ChatInput.tsx`](https://github.com/agegr/pi-web/blob/main/components/ChatInput.tsx)** and **[`components/MarkdownBody.tsx`](https://github.com/agegr/pi-web/blob/main/components/MarkdownBody.tsx)** – Handle user input and message rendering

## Backend Logic and Core Libraries in lib/

The **`lib/`** directory contains the server-side TypeScript modules that power Pi-web's agent communication and file system operations. These modules are imported by API routes in `app/api/` and by client-side hooks.

### Agent Client and Session Management

The **[`lib/agent-client.ts`](https://github.com/agegr/pi-web/blob/main/lib/agent-client.ts)** file exports `createAgentClient()`, a typed wrapper around the `/api/agent/*` endpoints that manages communication with running sessions. For session lifecycle and object reuse, **[`lib/rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/lib/rpc-manager.ts)** handles creation, pooling, and cleanup of `AgentSession` objects, ensuring efficient resource utilization.

### File System and Worktree Handling

Security-checked file operations live in **[`lib/file-access.ts`](https://github.com/agegr/pi-web/blob/main/lib/file-access.ts)**, which exports functions like `readFileFromRoot()` that restrict access to permitted roots including session working directories and worktree paths. Git worktree operations reside in **[`lib/worktree.ts`](https://github.com/agegr/pi-web/blob/main/lib/worktree.ts)**, providing logic for discovery, creation, and removal of worktrees. Utility functions for data normalization are located in **[`lib/normalize.ts`](https://github.com/agegr/pi-web/blob/main/lib/normalize.ts)**, and shared type definitions live in **[`lib/pi-types.ts`](https://github.com/agegr/pi-web/blob/main/lib/pi-types.ts)**.

## Documentation and CLI Utilities

### Markdown Guides in docs/

The **`docs/`** directory contains project documentation including [`release.md`](https://github.com/agegr/pi-web/blob/main/release.md) for version notes, [`worktrees.md`](https://github.com/agegr/pi-web/blob/main/worktrees.md) for git worktree usage instructions, and [`i18n.md`](https://github.com/agegr/pi-web/blob/main/i18n.md) for internationalization guidelines. These files provide migration guidance and architectural decisions for contributors.

### Development Scripts in bin/

The **`bin/`** folder contains small Node.js CLI helpers used during development. The primary script **[`bin/pi-web.js`](https://github.com/agegr/pi-web/blob/main/bin/pi-web.js)** implements commands for worktree management, while [`bin/pi-web-options.js`](https://github.com/agegr/pi-web/blob/main/bin/pi-web-options.js) handles argument parsing and [`bin/node-version.js`](https://github.com/agegr/pi-web/blob/main/bin/node-version.js) manages Node.js environment checks. These utilities are executed directly via Node, for example: `node bin/pi-web.js worktree add --cwd /path/to/repo --branch feature-x`.

## Practical Code Examples

### Accessing a Session via the Agent Client

```typescript
import { createAgentClient } from '@/lib/agent-client';

// Example: fetch the current state of a running session
async function getSessionState(sessionId: string) {
  const client = createAgentClient(sessionId);
  const state = await client.getState();   // GET /api/agent/[id]
  return state;
}

```

*Source: [`lib/agent-client.ts`](https://github.com/agegr/pi-web/blob/main/lib/agent-client.ts)*

### Reading Files Through the Security Layer

```typescript
import { readFileFromRoot } from '@/lib/file-access';

async function readUserFile(relativePath: string) {
  // Only allowed roots (session cwd, worktree roots, ~/pi-cwd-*) are permitted
  const content = await readFileFromRoot(relativePath);
  console.log(content);
}

```

*Source: [`lib/file-access.ts`](https://github.com/agegr/pi-web/blob/main/lib/file-access.ts)*

### Rendering the Chat Interface

```tsx
import ChatWindow from '@/components/ChatWindow';

export default function Page() {
  return (
    <div className="h-screen flex flex-col">
      <ChatWindow sessionId="1234-abcd" />
    </div>
  );
}

```

*Source: [`components/ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/components/ChatWindow.tsx)*

### Managing Worktrees via CLI

```bash
node bin/pi-web.js worktree add --cwd /path/to/repo --branch feature-x

```

*Implemented in: [`bin/pi-web.js`](https://github.com/agegr/pi-web/blob/main/bin/pi-web.js)*

## Summary

- **Pi-web** follows a standard Next.js TypeScript structure with clear separation between UI components (`components/`), page routing (`app/`), and business logic (`lib/`).
- The **`lib/`** directory contains critical server-side modules including [`agent-client.ts`](https://github.com/agegr/pi-web/blob/main/agent-client.ts) for session communication and [`file-access.ts`](https://github.com/agegr/pi-web/blob/main/file-access.ts) for secure file operations.
- All source code uses TypeScript (`.ts` or `.tsx`), while test files use the `.test.mjs` extension and co-locate with their source modules.
- Documentation lives in **`docs/`**, development CLI tools reside in **`bin/`**, and the root contains standard Next.js configuration files.
- Key entry points include [`app/page.tsx`](https://github.com/agegr/pi-web/blob/main/app/page.tsx) for the UI root and [`lib/agent-client.ts`](https://github.com/agegr/pi-web/blob/main/lib/agent-client.ts) for backend agent interactions.

## Frequently Asked Questions

### What is the main entry point for Pi-web's user interface?

The main entry point is **[`app/page.tsx`](https://github.com/agegr/pi-web/blob/main/app/page.tsx)**, which renders the root page component and serves as the initial load point for the Next.js application. This file imports components like `ChatWindow` and `SessionSidebar` from the `components/` directory to build the initial layout.

### Where does Pi-web store its server-side business logic?

Server-side logic resides in the **`lib/`** directory, specifically in files like [`agent-client.ts`](https://github.com/agegr/pi-web/blob/main/agent-client.ts) for agent communication, [`file-access.ts`](https://github.com/agegr/pi-web/blob/main/file-access.ts) for secure file operations, and [`rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/rpc-manager.ts) for session lifecycle management. These modules are consumed by API routes and server-side rendering functions.

### How are tests organized in the Pi-web repository?

Tests use the `.test.mjs` extension and sit alongside the modules they test rather than in a separate directory. For example, `lib/file-access.test.mjs` tests the functions exported by [`lib/file-access.ts`](https://github.com/agegr/pi-web/blob/main/lib/file-access.ts), keeping related code physically close and making import paths simple to manage.

### What directory contains Pi-web's command-line utilities?

CLI utilities and development scripts are located in the **`bin/`** directory. The primary script [`bin/pi-web.js`](https://github.com/agegr/pi-web/blob/main/bin/pi-web.js) provides worktree management commands, while supporting files like [`pi-web-options.js`](https://github.com/agegr/pi-web/blob/main/pi-web-options.js) handle configuration parsing for development workflows.