# Where to Find the Frontend Source Code in pi-web: Complete Directory Guide

> Locate pi-web frontend source code easily. This guide details the Next.js React TypeScript directory structure: app, components, hooks, and lib. Find what you need fast.

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

---

**The frontend source code in pi-web lives in the repository root as a Next.js React application written in TypeScript, organized across `app/`, `components/`, `hooks/`, and `lib/` directories.**

All user interface code for the **agegr/pi-web** repository resides at the top level and implements a modern React architecture using Next.js app router conventions. The frontend handles everything from the sidebar navigation and chat streaming to file viewers and model configuration panels. Understanding the directory structure allows you to trace the rendering flow from the initial page load through to individual message components.

## Frontend Directory Structure

The frontend source code in pi-web follows a standard Next.js 13+ app directory pattern. Four primary directories contain the entire client-side implementation:

- **`app/`** – Contains Next.js page routes and the top-level layout that bootstraps the UI. This includes [`app/page.tsx`](https://github.com/agegr/pi-web/blob/main/app/page.tsx) for the home page and [`app/layout.tsx`](https://github.com/agegr/pi-web/blob/main/app/layout.tsx) for global metadata and theme handling.
- **`components/`** – Houses reusable React components including [`AppShell.tsx`](https://github.com/agegr/pi-web/blob/main/AppShell.tsx) for the main layout, [`ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/ChatWindow.tsx) for message rendering, and [`SessionSidebar.tsx`](https://github.com/agegr/pi-web/blob/main/SessionSidebar.tsx) for navigation.
- **`hooks/`** – Stores custom React hooks such as [`useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/useAgentSession.ts) for SSE stream management, [`useI18n.ts`](https://github.com/agegr/pi-web/blob/main/useI18n.ts) for internationalization, and [`useAudio.ts`](https://github.com/agegr/pi-web/blob/main/useAudio.ts) for sound controls.
- **`lib/`** – Provides shared utilities like [`chat-lazy-load.ts`](https://github.com/agegr/pi-web/blob/main/chat-lazy-load.ts) for paginated history, [`message-display.ts`](https://github.com/agegr/pi-web/blob/main/message-display.ts) for message formatting, and [`file-paths.ts`](https://github.com/agegr/pi-web/blob/main/file-paths.ts) for path manipulation.

## Application Entry Points

The frontend initialization follows a hierarchical structure starting with Next.js layout conventions and mounting the primary application shell.

### Root Layout Configuration

The file [`app/layout.tsx`](https://github.com/agegr/pi-web/blob/main/app/layout.tsx) defines the global HTML structure, metadata tags, and theme injection points. It wraps every page in the document body and configures viewport settings, favicons, and CSS variables for theming. This layout serves as the foundation that persists across route changes.

### Home Page Rendering

The [`app/page.tsx`](https://github.com/agegr/pi-web/blob/main/app/page.tsx) file renders the main UI within a `<Suspense>` boundary and initializes the `I18nProvider` for internationalization support. This page imports the `AppShell` component and passes initial session data, acting as the bridge between Next.js routing and the React component tree.

## Core UI Components

The `components/` directory contains the visual building blocks of the interface, orchestrated by a top-level shell component.

### AppShell Component

[`components/AppShell.tsx`](https://github.com/agegr/pi-web/blob/main/components/AppShell.tsx) serves as the primary layout orchestrator, managing the sidebar, top navigation bar, right-hand file panel, and central chat area. It wires up global keyboard shortcuts, handles theme toggling, and manages project-trust states. All major layout decisions and responsive behavior originate from this file.

### Chat Window Implementation

[`components/ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/components/ChatWindow.tsx) contains the bulk of the interaction logic for the frontend source code in pi-web. It manages streaming message display, tool-call folding interfaces, lazy-loading of historical conversations, and the message composer at the bottom of the viewport. This component imports `useAgentSession` to maintain the Server-Sent Events (SSE) connection with the backend.

## State Management and Utilities

Supporting logic lives outside components in dedicated hooks and library folders to maintain separation of concerns.

### Custom React Hooks

The `hooks/` directory abstracts complex stateful logic into reusable functions:

- **[`useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/useAgentSession.ts)** – Handles the SSE stream connection, real-time message updates, and session lifecycle management.
- **[`useI18n.ts`](https://github.com/agegr/pi-web/blob/main/useI18n.ts)** – Provides translation utilities and locale detection.
- **[`useAudio.ts`](https://github.com/agegr/pi-web/blob/main/useAudio.ts)** – Manages audio playback controls and sound effect triggers.

### Shared Library Functions

The `lib/` directory contains pure utility functions:

- **[`chat-lazy-load.ts`](https://github.com/agegr/pi-web/blob/main/chat-lazy-load.ts)** – Implements intersection observer logic for paginated loading of chat history.
- **[`message-display.ts`](https://github.com/agegr/pi-web/blob/main/message-display.ts)** – Formats assistant messages, handles tool call rendering, and manages message compaction.
- **[`file-paths.ts`](https://github.com/agegr/pi-web/blob/main/file-paths.ts)** – Normalizes and manipulates file system paths displayed in the UI.

## Practical Implementation Example

When building features that extend the chat interface, you import components directly from the `components/` directory using path aliases:

```tsx
import { ChatWindow } from "@/components/ChatWindow";
import { SessionInfo } from "@/lib/types";

type Props = {
  session: SessionInfo | null;
  newSessionCwd: string | null;
};

export function MainChat({ session, newSessionCwd }: Props) {
  return (
    <ChatWindow
      session={session}
      newSessionCwd={newSessionCwd}
      newSessionDraftKey={null}
      onAgentEnd={() => console.log("session finished")}
    />
  );
}

```

The component integrates with hooks like `useAgentSession` and `useI18n` to manage backend connectivity and localization without cluttering the presentational logic.

## Key Files for Frontend Development

When navigating the frontend source code in pi-web, prioritize these specific files:

- **[`app/page.tsx`](https://github.com/agegr/pi-web/blob/main/app/page.tsx)** – Entry point showing how `AppShell` mounts and receives initial props.
- **[`app/layout.tsx`](https://github.com/agegr/pi-web/blob/main/app/layout.tsx)** – Global configuration for metadata and theme injection.
- **[`components/AppShell.tsx`](https://github.com/agegr/pi-web/blob/main/components/AppShell.tsx)** – Core layout logic for the three-panel interface design.
- **[`components/ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/components/ChatWindow.tsx)** – Message rendering, streaming states, and composer integration.
- **[`components/ChatInput.tsx`](https://github.com/agegr/pi-web/blob/main/components/ChatInput.tsx)** – Input bar implementation featuring model picker, tool presets, and thinking level controls.
- **[`hooks/useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/hooks/useAgentSession.ts)** – SSE connection management and real-time update handling.
- **[`lib/chat-lazy-load.ts`](https://github.com/agegr/pi-web/blob/main/lib/chat-lazy-load.ts)** – Pagination logic for efficient chat history rendering.

## Summary

- The frontend source code in pi-web resides in `app/`, `components/`, `hooks/`, and `lib/` directories at the repository root.
- **[`app/layout.tsx`](https://github.com/agegr/pi-web/blob/main/app/layout.tsx)** and **[`app/page.tsx`](https://github.com/agegr/pi-web/blob/main/app/page.tsx)** serve as the Next.js entry points for the React application.
- **[`components/AppShell.tsx`](https://github.com/agegr/pi-web/blob/main/components/AppShell.tsx)** orchestrates the main three-panel layout including sidebar, chat area, and file viewer.
- **[`components/ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/components/ChatWindow.tsx)** handles the complex streaming message logic and user input.
- Custom hooks in **`hooks/`** abstract SSE connections and internationalization away from UI components.

## Frequently Asked Questions

### What framework does pi-web use for its frontend?

pi-web uses **Next.js** with the App Router architecture, written in **TypeScript** and styled with standard CSS. The frontend leverages React Server Components where appropriate while client-side interactivity relies on traditional React hooks and Suspense boundaries.

### Where is the main layout defined in pi-web?

The main layout definition lives in **[`components/AppShell.tsx`](https://github.com/agegr/pi-web/blob/main/components/AppShell.tsx)**, which is imported by **[`app/page.tsx`](https://github.com/agegr/pi-web/blob/main/app/page.tsx)**. While [`app/layout.tsx`](https://github.com/agegr/pi-web/blob/main/app/layout.tsx) provides the HTML document wrapper, [`AppShell.tsx`](https://github.com/agegr/pi-web/blob/main/AppShell.tsx) defines the actual three-column interface structure including the sidebar, top bar, and content areas.

### How does pi-web handle chat streaming in the frontend?

Chat streaming utilizes **Server-Sent Events (SSE)** managed by the **[`useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/useAgentSession.ts)** hook. This hook maintains the connection state, parses incoming message chunks, and updates the React state to trigger re-renders in **[`components/ChatWindow.tsx`](https://github.com/agegr/pi-web/blob/main/components/ChatWindow.tsx)**, which displays the streaming text with appropriate loading indicators.

### What is the purpose of the hooks directory in pi-web?

The **`hooks/`** directory contains custom React hooks that extract complex logic from components. These include state management for agent sessions, internationalization utilities, audio handling, and drag-and-drop functionality. Separating this logic allows components in `components/` to remain focused on presentation while reusable business logic stays testable and shareable.