Architecture

This document provides a high-level overview of the Nanobrowser project architecture. It is intended for developers who wish to understand the codebase and contribute to the project.

Monorepo Structure

Nanobrowser is a monorepo using pnpm workspaces for managing packages and Turbo for build orchestration. This structure allows for modular code, shared utilities, and efficient builds.

The project is organized into three main directories:

• chrome-extension/: The core of the Chrome extension, containing the manifest, background service worker, and the multi-agent system.
• pages/: UI packages for the different parts of the extension's interface, built with React and Vite. Each subdirectory is a separate application.
  • side-panel/: The main chat interface.
  • options/: The extension's settings page.
  • content/: The content script injected into web pages.
• packages/: Shared libraries and configurations used across the monorepo.
  • shared/: Common utilities and TypeScript types.
  • storage/: A wrapper around Chrome's extension storage API.
  • ui/: Shared React components.
  • i18n/: Internationalization setup.
  • And others for configuration (vite-config, tailwind-config, tsconfig).

Multi-Agent System

The core AI logic is a multi-agent system located in chrome-extension/src/background/agent/. It consists of specialized agents that collaborate to execute user tasks:

• Planner: A high-level agent responsible for strategic thinking. It analyzes the user's goal, observes the current state of the browser, and creates a plan or suggests the next logical step.
• Navigator: The execution agent that interacts directly with the web page. It takes instructions from the Planner and performs actions like clicking elements, typing text, and navigating URLs.
• Validator: (As described in CLAUDE.md) Validates task completion and results.

These agents communicate and coordinate through the background service worker, using LangChain.js for LLM integration and Chrome APIs for browser automation.

Build System

The project's build process is managed by several key technologies:

• Turbo: An intelligent build system that orchestrates tasks across the monorepo. It caches build outputs to speed up subsequent builds, only re-running tasks when source files have changed.
• Vite: A modern frontend build tool that bundles each workspace (chrome-extension, side-panel, etc.) independently. It provides fast Hot Module Replacement (HMR) for a smooth development experience.
• TypeScript: Used across the entire project for static typing, ensuring code reliability and maintainability.
• ESLint & Prettier: Enforce consistent code style and quality standards across all packages.