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

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 for the home page and app/layout.tsx for global metadata and theme handling.
• components/ – Houses reusable React components including AppShell.tsx for the main layout, ChatWindow.tsx for message rendering, and SessionSidebar.tsx for navigation.
• hooks/ – Stores custom React hooks such as useAgentSession.ts for SSE stream management, useI18n.ts for internationalization, and useAudio.ts for sound controls.
• lib/ – Provides shared utilities like chat-lazy-load.ts for paginated history, message-display.ts for message formatting, and 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 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 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 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 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 – Handles the SSE stream connection, real-time message updates, and session lifecycle management.
• useI18n.ts – Provides translation utilities and locale detection.
• useAudio.ts – Manages audio playback controls and sound effect triggers.

Shared Library Functions

The lib/ directory contains pure utility functions:

• chat-lazy-load.ts – Implements intersection observer logic for paginated loading of chat history.
• message-display.ts – Formats assistant messages, handles tool call rendering, and manages message compaction.
• 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:

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 – Entry point showing how AppShell mounts and receives initial props.
• app/layout.tsx – Global configuration for metadata and theme injection.
• components/AppShell.tsx – Core layout logic for the three-panel interface design.
• components/ChatWindow.tsx – Message rendering, streaming states, and composer integration.
• components/ChatInput.tsx – Input bar implementation featuring model picker, tool presets, and thinking level controls.
• hooks/useAgentSession.ts – SSE connection management and real-time update handling.
• 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 and app/page.tsx serve as the Next.js entry points for the React application.
• components/AppShell.tsx orchestrates the main three-panel layout including sidebar, chat area, and file viewer.
• 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, which is imported by app/page.tsx. While app/layout.tsx provides the HTML document wrapper, 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 hook. This hook maintains the connection state, parses incoming message chunks, and updates the React state to trigger re-renders in 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.

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