Global Overviews: Your Map to Onlook’s Product and Technology

Before exploring the detailed design and implementation of Onlook’s individual modules, it is essential to first establish a comprehensive, high-level understanding of the platform as a whole. This section provides a foundational map, guiding you through Onlook’s overall user experience, its fundamental capabilities, and the underlying technical structure that brings it all to life. This global perspective is designed to provide context and direction, helping you connect the dots as we delve into each component in detail.

Overall Product UI/UX Overview: The User’s Journey and Interface Experience

Onlook is designed as a unified, single-page application, serving as a central hub for AI-powered web development. The user experience focuses on creating and modifying web applications through an intuitive visual interface, driven by natural language and real-time feedback.

User Journey Map

The user’s core journey with Onlook is a seamless cycle of creation, AI-powered iteration, and deployment. A user starts with an idea, uses natural language to generate and refine a web application on a live canvas, and finally publishes the production-ready code.

Key Interface Areas

The Onlook interface is composed of several core areas, each designed to support specific development tasks:

Interface / Area	Primary Function	Key User Experience
Main Editor Workspace	Central hub for AI-powered web development, combining tools.	Offers a comprehensive environment with live preview, AI interaction, and flexible control panels, acting as your primary development area with full-screen immersive experience.
Project Dashboard	View, manage, and create projects.	Provides an organized overview of all your projects, allowing quick access to existing work or the initiation of new projects through clear, card-based displays and intuitive dialogs.
Left Panel System	Multi-tab navigation for project structure and assets.	Features five dedicated tabs: Layers (element hierarchy), Brand (design tokens), Pages (navigation), Images (asset management), and Branches (version control). Supports both hover-to-open and click-to-lock interactions.
Right Panel System	AI interaction and code development tools.	Contains the AI Chat interface for natural language programming and a Code tab for direct code editing. Includes chat history, conversation controls, and real-time code synchronization.
Central Canvas	Interactive preview and visual editing environment.	Displays your application live with instant updates, supports direct element selection and manipulation, right-click context menus, and zoom controls for detailed editing work.
Top Navigation Bar	Project-level controls and settings access.	Provides access to project settings, deployment options, collaboration features, and account management with a clean, minimal interface that doesn’t interfere with the editing experience.
Bottom Status Bar	Real-time feedback and quick actions.	Shows project status, build information, error notifications, and provides quick access to common actions without taking up valuable screen real estate.
Editor Toolbar	Context-sensitive editing controls.	Dynamically appears when elements are selected, offering relevant styling options, text editing controls, layout adjustments, and other contextual tools positioned intelligently to avoid blocking the work area.
Modal Dialogs & Overlays	Present critical information, confirmations, and settings.	Provides a consistent and accessible way to present important information or gather user input without disrupting the main workflow, including settings modals, pricing dialogs, and confirmation prompts.
Resizable Panel System	Customizable workspace layout with flexible boundaries.	Allows users to adjust panel widths and workspace proportions according to their current task and screen size, with intelligent constraints to maintain usability across different viewport sizes.

Overall Visual Characteristics

Onlook’s visual design is modern, clean, and tool-focused, utilizing a dark-mode-first aesthetic. It blends clear functionality with polished visual elements, ensuring a professional and engaging user experience through a consistent color palette, typography, spacing, and subtle animations.

Core Functionalities Overview: What Onlook Does at its Heart

Onlook provides a comprehensive set of core functionalities designed to streamline the web application development process, from initial concept to deployment. These functions empower users to build and modify applications efficiently, leveraging AI for key development tasks.

Onlook’s Core Capabilities

Functional Area	What Onlook Does	Why This Matters for Users
AI-Powered Code Generation & Editing	Generates new UI components, pages, and modifies existing code based on natural language descriptions. Provides context-aware editing and intelligent suggestions for next development steps.	Allows users to quickly transform ideas into functional code or make precise changes to existing applications simply by describing their intent, with AI acting as an intelligent development partner.
Interactive Real-time Preview	Provides an immediate, live, and fully interactive display of the application being built, powered by CodeSandbox integration with hot-reload capabilities.	Offers instant visual feedback on all code changes, enables direct manipulation for AI editing, and supports testing for responsive design across different devices with zero setup time.
Visual Development Environment	Offers a comprehensive visual editor with drag-and-drop functionality, element selection, right-click context menus, and Figma-like UI controls for direct manipulation.	Enables designers and developers to work visually without losing the power of code, bridging the gap between design tools and development environments.
Project Creation & Import System	Supports creating projects from scratch, importing existing local projects, importing from GitHub repositories, and using pre-built templates.	Provides flexibility for users to start new projects or bring existing work into the visual development environment, accommodating different workflow preferences.
Comprehensive Asset Management	Manages project layers, brand assets (colors, fonts, design tokens), pages, images, and file structures through dedicated management panels.	Organizes all project resources in an intuitive way, making it easy to maintain consistency and navigate complex projects as they grow.
Advanced Development Tools	Includes real-time code editing, terminal command execution, error detection and handling, screenshot capture, and file system synchronization.	Provides professional development capabilities within the visual environment, ensuring users don’t sacrifice functionality for ease of use.
Integrated Project Version Control	Tracks all changes, saves project snapshots (checkpoints), creates parallel development paths (branches), and provides comprehensive history review.	Protects work from loss, facilitates experimentation with new features independently, and provides a clear audit trail of project evolution without complex external tools.
Multi-Panel Workspace	Features customizable left panel (layers, brand, pages, images, branches), right panel (AI chat, code editor), and central canvas with resizable components.	Allows users to organize their workspace according to their preferences and current task, maximizing productivity through flexible layout options.
Deployment and Publishing	Enables users to deploy their web applications to the internet, manage custom domains, generate shareable preview links, and sync with GitHub repositories.	Simplifies the process of making applications live quickly, providing options for basic hosting, professional branding, and seamless integration with existing development workflows.
Collaborative Features	Supports team collaboration, member management, and shared project access (with real-time editing capabilities in development).	Enables teams to work together on projects efficiently, sharing resources and maintaining consistency across team members’ contributions.
User and Account Management	Handles secure user authentication, manages session security, oversees subscription plans, and provides usage analytics and billing management.	Provides secure access to the platform, personalizes feature availability based on subscription status, and offers transparent management of billing information with detailed usage insights.

Overall Technical Architecture Overview: The System’s Components and Interactions

Onlook is structured as a monorepo, meaning all its distinct parts (applications and shared libraries) are managed within a single code repository. This organization facilitates code sharing, simplifies dependency management, and supports a layered system architecture that enables its advanced functionalities.

Onlook’s Core Technology Stack

Onlook leverages a modern and robust set of technologies to deliver its AI-powered development experience. This table categorizes the key technologies by their primary layer within the system:

Layer	Technology Name	Primary Role in Onlook’s System
Frontend	Next.js & React	Builds the user-facing web application, including the editor workspace and interactive preview.
	Radix UI & shadcn/ui	Provides accessible, pre-built UI components (like buttons, dialogs) that form the application’s design system and ensure a consistent look and feel.
	Tailwind CSS	A styling framework used to design the visual appearance of all user interface components through utility classes.
	MobX	State management library that provides reactive state management for the complex editor interface and real-time updates.
Backend	Node.js	The server-side runtime environment where the application’s core logic runs and coordinates with other services.
	tRPC	A tool for creating type-safe APIs, ensuring consistent and error-free data communication between frontend and backend.
	Fastify	A fast and low-overhead web framework used to host the tRPC APIs on the backend server.
AI & Code Processing	Large Language Models (LLMs)	Provides the core intelligence for understanding natural language, generating code modification instructions, and offering development assistance.
	Vercel AI SDK	The primary toolkit for integrating LLMs, providing a standard way to communicate with different AI providers.
	OpenRouter	LLM model provider that gives access to multiple AI models through a unified API.
	Morph Fast Apply & Relace	Specialized fast apply model providers for efficient code modifications.
	Abstract Syntax Tree (AST)	Code Structure Representation: A tree-like data structure used to understand, precisely modify, and generate syntactically correct code.
	Babel	Code Parser and Transformer: The tooling used to convert code into ASTs, apply modifications, and convert ASTs back into code.
Sandbox & Preview	CodeSandbox SDK	Powers the real-time preview environment, providing a full development sandbox with hot-reload capabilities.
	Penpal	Cross-Frame Communication: A specialized utility for secure, bi-directional communication between the main editor and the isolated live preview iframe.
Data & Persistence	Supabase (PostgreSQL)	The database service used to store all persistent application data, including user accounts, projects, and version history.
	Drizzle ORM	A tool that allows developers to interact with the PostgreSQL database using TypeScript code, enhancing safety and development speed.
Hosting & Deployment	Freestyle	Hosting platform for deploying and serving the built applications with custom domain support.
Infrastructure & Utilities	isomorphic-git	In-Browser Git Library: Enables full Git version control operations directly within the web browser, powering project history tracking.
	Bun	Monorepo Manager: A fast JavaScript toolkit used to manage the entire project structure, dependencies, and script execution.
	Docker	Container management for consistent development and deployment environments.
	Stripe	Payment Processing: Manages user subscriptions, upgrades, and billing functionalities.
	GitHub Integration	Handles user login (OAuth), GitHub App installations, and synchronization of project code with user repositories.
	PostHog	Analytics and user behavior tracking to understand how users interact with the platform.
	Langfuse	An observability platform specifically for LLM applications, used to trace, debug, and monitor the AI’s behavior and performance.

System Organization and Key Interactions

The Onlook project is structured as a monorepo, meaning all its distinct parts (applications and shared libraries) are stored in a single code repository. This organization promotes code sharing and simplifies dependency management. The system is logically divided into several layers that work together.

The main application consists of a frontend (what the user sees) and a backend (where the logic runs). These are supported by a collection of specialized, reusable packages (shared libraries) that handle specific tasks like AI, code parsing, database interactions, and UI.

Data Flow: From Prompt to Code

To understand how the system works, let’s trace the data flow for the core user action: providing a natural language prompt to generate or change code.

The process involves the user’s request traveling from the frontend to the backend, being processed by the AI, and then returning as code changes that are applied and displayed in the live preview.

Code Map: Navigating Onlook’s Repository Structure

Understanding Onlook’s codebase begins with its top-level organization. As a monorepo, the project is structured into apps/ for distinct applications and packages/ for shared libraries. This map provides a detailed overview of key directories and their primary purpose.

Module	Sub-module	Key Sub-component / File	Description -
Applications (`apps/`)	`web/`	`client/`	Contains the main Next.js frontend application, including all user interface components and client-side logic. -
		`server/`	Contains the Node.js backend server that hosts the tRPC APIs, handling business logic and service orchestration. -
	`backend/`	`supabase/`	Contains configurations and potentially database migrations or functions related to Supabase, Onlook’s backend-as-a-service provider. -
Shared Libraries (`packages/`)	`ai/`	`prompt/`, `chat/`, `tools/`	Contains the core AI capabilities, including system prompt definitions (`system.ts`), contextual prompt construction (`provider.ts`), LLM provider integration (`providers.ts`), and the AI’s executable tools (e.g., `web.ts`, `cli.ts`). -
	`db/`	`schema/`, `mappers/`, `client.ts`	Manages database interaction, including Drizzle ORM schema definitions for all tables, data mapping logic, and the database client setup. -
	`git/`	`git.ts`	Implements the in-browser Git version control system by encapsulating `isomorphic-git` operations. -
	`github/`	`auth.ts`, `installation.ts`	Handles GitHub authentication via OAuth flows and manages GitHub App installations for API integration. -
	`models/`	`project/`, `actions/`, `user/`	Contains all shared TypeScript data models and interfaces, ensuring data consistency across the application. -
	`parser/`	`parse.ts`, `code-edit/`	Manages code parsing, Abstract Syntax Tree (AST) manipulation, and code generation, with `transform.ts` being key for applying AI changes. -
	`penpal/`	`parent.ts`, `child.ts`	Implements the cross-frame communication library for secure interaction between the main editor and the iframe preview. -
	`rpc/`	`trpc/`	Defines and configures the tRPC API routers, which are hosted in `apps/web/server/`. -
	`stripe/`	`functions.ts`, `constants.ts`	Manages Stripe payment and subscription integration, including API call logic and subscription plan definitions. -
	`ui/`	`components/`, `tailwind.config.ts`	Onlook’s reusable UI component library, containing all UI elements (e.g., `button.tsx`, `dialog.tsx`) and styling configurations. -
	`utility/`	`urls.ts`, `assert.ts`, `id.ts`	A collection of general utility functions used across the codebase for tasks like URL validation, assertions, and ID generation. -

Functional Role	Code File	Description
Global Application Layout	`apps/web/client/src/app/layout.tsx`	Defines the main layout and structure for the entire web application.
Next.js Configuration	`next.config.ts`	Configuration file for the Next.js framework, controlling build and runtime behavior.
Tailwind CSS Configuration	`tailwind.config.ts`	Configuration file for Tailwind CSS, defining design tokens and utility classes.
Core Data Models Barrel File	`packages/models/src/index.ts`	Re-exports various data models used throughout the application, providing a central access point.
Main tRPC API Router	`packages/rpc/src/index.ts`	Defines the main tRPC router, exposing backend API endpoints to the frontend.
Supabase Session Middleware	`apps/web/client/src/middleware.ts`	Handles Supabase session management and authentication checks for all incoming requests.

Version Control AI Code Gen