# agegr/pi-web App Structure: Main Directories and Architecture Explained

> Explore the agegr/pi-web app structure. Understand the main directories like app/, components/, hooks/, lib/, public/, docs/, and bin/ for efficient Next.js development.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: architecture
- Published: 2026-08-09

---

**The agegr/pi-web repository organizes its Next.js application into seven functional directories: `app/` for routing and layouts, `components/` for reusable UI, `hooks/` for client-side logic, `lib/` for server utilities and business logic, `public/` for static PWA assets, `docs/` for markdown guides, and `bin/` for command-line scripts.**

The `agegr/pi-web` application follows a standard Next.js project structure with clear separation of concerns across its top-level folders. Understanding this directory layout is essential for developers contributing to the codebase or extending its chat-based interface and worktree management features. Each folder serves a distinct architectural purpose, from rendering React components in the browser to managing Git worktrees on the server.

## Top-Level Directory Overview

The codebase groups related functionality into seven primary folders at the repository root:

- **`app/`** - Contains Next.js page and layout definitions, global CSS, and the Progressive Web App (PWA) manifest.
- **`components/`** - Houses reusable React UI components including the chat window, sidebar, and file explorer.
- **`hooks/`** - Encapsulates custom React hooks for client-side logic such as session handling, theming, and keyboard shortcuts.
- **`lib/`** - Stores server-side utilities, TypeScript type definitions, and core business logic including worktree management and markdown processing.
- **`public/`** - Serves static assets via the Next.js server, including the service worker, offline page, and icons.
- **`docs/`** - Contains Markdown documentation for developers and end-users, covering worktree guides and internationalization.
- **`bin/`** - Provides small command-line entry points used by the project, specifically [`pi-web.js`](https://github.com/agegr/pi-web/blob/main/pi-web.js) and [`pi-web-options.js`](https://github.com/agegr/pi-web/blob/main/pi-web-options.js).

Root-level configuration files such as [`package.json`](https://github.com/agegr/pi-web/blob/main/package.json), [`next.config.ts`](https://github.com/agegr/pi-web/blob/main/next.config.ts), and [`README.md`](https://github.com/agegr/pi-web/blob/main/README.md) provide project metadata and build configuration.

## Core Application Directories Explained

### app/ - Next.js Routing and Global Configuration

The `app/` directory implements the Next.js App Router structure. The file [`app/layout.tsx`](https://github.com/agegr/pi-web/blob/main/app/layout.tsx) defines the global layout that wraps all pages and injects providers used throughout the UI. This directory also contains page-specific route handlers and the PWA manifest configuration.

### components/ - Reusable React UI

All visual interface elements live in `components/`. The [`SessionSidebar.tsx`](https://github.com/agegr/pi-web/blob/main/SessionSidebar.tsx) file implements the sidebar listing active sessions, worktrees, and file explorer navigation. Other components like [`ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/ChatWindow.tsx) handle the main chat interface rendering.

### hooks/ - Client-Side State and Effects

The `hooks/` directory encapsulates React logic that multiple components share. The [`useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/useAgentSession.ts) hook manages Server-Sent Events (SSE) connections, handling reconnection logic and state updates for agent sessions. The [`useTheme.ts`](https://github.com/agegr/pi-web/blob/main/useTheme.ts) hook provides theming capabilities across the application.

### lib/ - Server-Side Business Logic

Server-side utilities and core business logic reside in `lib/`. The [`worktree.ts`](https://github.com/agegr/pi-web/blob/main/worktree.ts) file contains the central logic for creating, listing, and deleting Git worktrees that power the worktree UI. The [`agent-client.ts`](https://github.com/agegr/pi-web/blob/main/agent-client.ts) file provides a typed wrapper around `/api/agent` endpoints, serving as the exclusive client-side gateway to backend services. Additional utilities like [`rpc-manager.ts`](https://github.com/agegr/pi-web/blob/main/rpc-manager.ts) expose functions such as `startRpcSession` for initiating remote procedure calls.

### public/ - Static Assets and PWA Support

The `public/` directory contains files served directly by the Next.js server at the root path. The [`sw.js`](https://github.com/agegr/pi-web/blob/main/sw.js) service worker enables offline support and PWA caching strategies. Static files like [`offline.html`](https://github.com/agegr/pi-web/blob/main/offline.html) provide fallback content when network connectivity is unavailable.

### docs/ and bin/ - Documentation and CLI Tools

The `docs/` directory contains [`worktrees.md`](https://github.com/agegr/pi-web/blob/main/worktrees.md), the authoritative guide for users on worktree organization. The `bin/` directory provides executable scripts including [`pi-web.js`](https://github.com/agegr/pi-web/blob/main/pi-web.js) and [`pi-web-options.js`](https://github.com/agegr/pi-web/blob/main/pi-web-options.js) for command-line interactions with the application.

## Cross-Directory Integration Patterns

The directories interconnect through specific import patterns that maintain clean architecture boundaries.

### Component-to-Hook Integration

Components import logic from `hooks/` to manage state and side effects:

```tsx
// File: components/AppShell.tsx
import SessionSidebar from "./SessionSidebar";
import ChatWindow from "./ChatWindow";
import { useTheme } from "../hooks/useTheme";

export default function AppShell() {
  useTheme();               // ← hook from hooks/
  return (
    <div className="app-shell">
      <SessionSidebar />    {/* component from components/ */}
      <ChatWindow />        {/* component from components/ */}
    </div>
  );
}

```

### Server Logic Coordination

Server-side modules within `lib/` call each other to orchestrate complex operations:

```ts
// File: lib/agent-client.ts
import { startRpcSession } from "./rpc-manager";

export async function createAgentSession(cwd: string, tools?: string[]) {
  const session = await startRpcSession({ cwd, toolNames: tools });
  return session;
}

```

### Static Asset References

Components reference files in `public/` using root-relative paths:

```tsx
// File: components/ChatWindow.tsx
export function OfflineNotice() {
  return (
    <img
      src="/offline.html"   // Served from public/
      alt="Offline"
    />
  );
}

```

## Essential Files for Developers

Several key files serve as primary entry points for common development tasks:

- **[`app/layout.tsx`](https://github.com/agegr/pi-web/blob/main/app/layout.tsx)** - Defines the global Next.js layout and provider injection.
- **[`components/SessionSidebar.tsx`](https://github.com/agegr/pi-web/blob/main/components/SessionSidebar.tsx)** - Implements the navigation sidebar for sessions and worktrees.
- **[`hooks/useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/hooks/useAgentSession.ts)** - Core hook for streaming agent events with automatic reconnection.
- **[`lib/worktree.ts`](https://github.com/agegr/pi-web/blob/main/lib/worktree.ts)** - Central API for Git worktree manipulation.
- **[`lib/agent-client.ts`](https://github.com/agegr/pi-web/blob/main/lib/agent-client.ts)** - Typed client for all backend agent communication.
- **[`public/sw.js`](https://github.com/agegr/pi-web/blob/main/public/sw.js)** - Service worker script controlling PWA offline capabilities.
- **[`docs/worktrees.md`](https://github.com/agegr/pi-web/blob/main/docs/worktrees.md)** - Comprehensive documentation for the worktree feature.

## Summary

- The `agegr/pi-web` app structure follows Next.js conventions with seven primary directories at the root level.
- **`app/`** handles routing and global layout, while **`components/`** contains the React UI implementation.
- **`hooks/`** extracts reusable client-side logic such as `useTheme` and `useAgentSession`.
- **`lib/`** consolidates server-side utilities including worktree management in [`worktree.ts`](https://github.com/agegr/pi-web/blob/main/worktree.ts) and agent communication in [`agent-client.ts`](https://github.com/agegr/pi-web/blob/main/agent-client.ts).
- **`public/`** serves PWA static assets including the service worker at [`sw.js`](https://github.com/agegr/pi-web/blob/main/sw.js).
- **`docs/`** and **`bin/`** provide user documentation and CLI tooling respectively.
- Cross-directory imports follow strict boundaries: components use hooks, lib modules call lib modules, and public assets are referenced via root paths.

## Frequently Asked Questions

### What is the purpose of the lib/ directory in agegr/pi-web?

The `lib/` directory contains server-side utilities, TypeScript type definitions, and core business logic for the application. It houses critical modules like [`worktree.ts`](https://github.com/agegr/pi-web/blob/main/worktree.ts) for Git worktree operations and [`agent-client.ts`](https://github.com/agegr/pi-web/blob/main/agent-client.ts) for typed communication with backend agent APIs, distinguishing it from the `components/` directory which handles only UI rendering.

### How does the hooks/ directory differ from components/ in this codebase?

While `components/` stores React UI elements like [`SessionSidebar.tsx`](https://github.com/agegr/pi-web/blob/main/SessionSidebar.tsx) and [`ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/ChatWindow.tsx), the `hooks/` directory contains reusable stateful logic such as [`useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/useAgentSession.ts) and [`useTheme.ts`](https://github.com/agegr/pi-web/blob/main/useTheme.ts). Hooks encapsulate client-side effects, SSE connections, and theming that multiple components share without rendering markup themselves.

### Where are static files like the service worker located in agegr/pi-web?

Static assets reside in the `public/` directory, which Next.js serves at the root URL path. The service worker implementation lives at [`public/sw.js`](https://github.com/agegr/pi-web/blob/main/public/sw.js), enabling PWA offline support, while other static files like [`offline.html`](https://github.com/agegr/pi-web/blob/main/offline.html) provide fallback content when network connectivity fails.

### Which directory contains the main application layout and routing configuration?

The `app/` directory contains the Next.js App Router configuration, with [`app/layout.tsx`](https://github.com/agegr/pi-web/blob/main/app/layout.tsx) defining the global layout that wraps all pages. This directory also holds page routes, global CSS, and the PWA manifest, making it the primary entry point for the application's routing structure.