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

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 and pi-web-options.js.

Root-level configuration files such as package.json, next.config.ts, and 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 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 file implements the sidebar listing active sessions, worktrees, and file explorer navigation. Other components like 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 hook manages Server-Sent Events (SSE) connections, handling reconnection logic and state updates for agent sessions. The 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 file contains the central logic for creating, listing, and deleting Git worktrees that power the worktree UI. The 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 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 service worker enables offline support and PWA caching strategies. Static files like offline.html provide fallback content when network connectivity is unavailable.

docs/ and bin/ - Documentation and CLI Tools

The docs/ directory contains worktrees.md, the authoritative guide for users on worktree organization. The bin/ directory provides executable scripts including pi-web.js and 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:

// 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:

// 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:

// 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 - Defines the global Next.js layout and provider injection.
• components/SessionSidebar.tsx - Implements the navigation sidebar for sessions and worktrees.
• hooks/useAgentSession.ts - Core hook for streaming agent events with automatic reconnection.
• lib/worktree.ts - Central API for Git worktree manipulation.
• lib/agent-client.ts - Typed client for all backend agent communication.
• public/sw.js - Service worker script controlling PWA offline capabilities.
• 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 and agent communication in agent-client.ts.
• public/ serves PWA static assets including the service worker at 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 for Git worktree operations and 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 and ChatWindow.tsx, the hooks/ directory contains reusable stateful logic such as useAgentSession.ts and 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, enabling PWA offline support, while other static files like 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 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.

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