Project Lifecycle & Publishing

The Project Lifecycle & Publishing system encompasses the complete project management workflow in Onlook, from initial project creation and import through comprehensive file system operations to final deployment and publishing. This system provides users with flexible project initiation options, robust file and asset management capabilities, and seamless publishing workflows that take projects from concept to live, accessible web applications.

Product Specifications

User Experience Flow

The project lifecycle in Onlook spans from initial creation through development to final publishing. Users can start projects in multiple ways: creating from scratch with AI assistance, importing existing local projects, using pre-built templates, or importing from GitHub repositories. Throughout development, the system manages all file operations and project resources automatically. When ready, users can deploy their projects with one-click publishing, add custom domains, and sync their code to GitHub repositories.

Functional Requirements

Feature	End-to-End Business Logic and Rules
Project Dashboard and Organization	User Intent: To efficiently manage multiple projects with intuitive organization, search capabilities, and quick access to recent work and favorite templates. End-to-End Flow: 1. Frontend - Project Overview: The dashboard displays all user projects in an organized, visual format with project thumbnails, names, descriptions, and last modified dates for quick identification and access. 2. System - Intelligent Organization: Projects are automatically organized with multiple sorting options (alphabetical, date created, last viewed) and filtering capabilities to help users find specific projects quickly. 3. Frontend - Search and Discovery: Users can search across project names, descriptions, and tags to quickly locate specific projects, with real-time filtering that updates results as they type. 4. System - Template Integration: The dashboard seamlessly integrates template browsing with personal projects, allowing users to discover new starting points while managing existing work. Key Rules & Constraints: - Project thumbnails must be automatically generated and updated to reflect current project state. - Search functionality must be fast and responsive even with large numbers of projects. - The interface must clearly distinguish between personal projects and available templates.
AI-Driven Project Creation	User Intent: To start a new web application project by describing their vision in natural language, with the AI generating the initial project structure and codebase. End-to-End Flow: 1. Frontend - Project Initiation: Users access the project dashboard and choose “Create New Project.” They provide a descriptive prompt about their desired application (e.g., “Create a modern portfolio website for a photographer”). 2. System - AI-Powered Name Generation: The system uses AI to generate an appropriate project name based on the user’s description, creating meaningful project identifiers that reflect the intended purpose. 3. Backend - Sandbox Environment Setup: The system creates a new CodeSandbox instance from a Next.js template, establishing a complete development environment with all necessary dependencies and build tools. 4. System - Project Database Creation: A new project record is created in the database with metadata including name, description, creation timestamp, and associations with the user account and sandbox environment. 5. Frontend - Editor Launch: The user is automatically redirected to the main editor interface where they can immediately begin working with their new project, with the AI ready to implement their initial vision. Key Rules & Constraints: - Each new project gets its own isolated CodeSandbox environment to prevent conflicts. - Project names must be unique within a user’s account to avoid confusion. - The initial project setup must include all necessary dependencies for Next.js and Tailwind CSS development.
Template-Based Project Creation	User Intent: To quickly start new projects using professionally designed, pre-built templates that demonstrate best practices and provide solid starting points for common use cases. End-to-End Flow: 1. Frontend - Template Discovery: Users browse a curated library of project templates displayed with preview images, descriptions, and feature highlights. Templates are organized by category and use case for easy discovery. 2. System - Template Selection and Customization: When a template is selected, users can customize basic properties like project name and description before creating their copy of the template. 3. Backend - Template Forking Process: The system creates a complete copy of the selected template by forking its CodeSandbox environment, duplicating all files, and establishing a new, independent project instance. 4. System - Personalization Integration: The new project is automatically associated with the user’s account, inherits their preferences and settings, and becomes available in their project dashboard alongside other projects. 5. Frontend - Immediate Access: Users are taken directly to the editor interface where they can begin customizing their template-based project using all available Onlook tools and AI assistance. Key Rules & Constraints: - Template projects must be marked with special tags to distinguish them from regular user projects. - Forked templates become completely independent projects with no ongoing connection to the original template. - Users can star favorite templates for quick access and organize templates by preference.
Local Project Import System	User Intent: To bring existing Next.js projects from their local development environment into Onlook’s visual editing and AI-powered development workflow. End-to-End Flow: 1. Frontend - Project Selection: Users initiate the import process by selecting a local project folder through a file browser interface. The system supports drag-and-drop folder selection for intuitive interaction. 2. System - Project Validation: The system analyzes the selected folder to validate it as a compatible Next.js project, checking for required files (package.json, Next.js configuration), supported dependencies, and proper project structure. 3. Backend - File Processing and Upload: All project files are processed and uploaded to a new CodeSandbox instance. The system handles file type detection, excludes unnecessary files (node_modules, build artifacts), and maintains the original project structure. 4. System - Dependency Resolution: The system analyzes the project’s package.json and automatically installs all dependencies in the CodeSandbox environment, ensuring the imported project can run immediately without configuration issues. 5. Frontend - Project Integration: Once import is complete, the project appears in the user’s dashboard and can be opened in the main editor with full access to all Onlook features including AI assistance and visual editing. Key Rules & Constraints: - Only Next.js projects with compatible configurations can be imported to ensure feature compatibility. - Large files and directories (over certain size limits) are automatically excluded to maintain performance. - The import process must preserve the original project’s functionality while adding Onlook’s enhancement capabilities.
One-Click Publishing to Subdomain	User Intent: To quickly and easily deploy their site to a publicly accessible URL for sharing or testing. End-to-End Flow: 1. Frontend - User Action: The user clicks the “Publish” button in the project interface. 2. System - Automatic Subdomain Generation: The system automatically generates a unique, memorable subdomain for the project using a combination of descriptive words and identifiers. 3. Backend - Deployment Process: The system packages the complete project, including all assets and dependencies, and deploys it to the hosting infrastructure through an abstracted hosting provider interface. 4. System - URL Activation: Once deployment is complete, the generated subdomain becomes active and accessible, with the system performing health checks to ensure the deployment is functioning correctly. 5. Frontend - Success Confirmation: The user receives immediate confirmation with the live URL, which they can share or use for testing purposes. Key Rules & Constraints: - Subdomain generation must ensure uniqueness across all deployed projects. - Deployment must be fast and reliable, with clear error reporting if issues occur. - Published sites must maintain full functionality and performance of the original development environment.
Custom Domain Management	User Intent: To serve their web application from a professional, branded domain name that they own. End-to-End Flow: 1. Frontend - User Action: The user enters their custom domain name (e.g., `www.my-startup.com`) into the input field and clicks “Add.” 2. Backend - Domain Registration: The backend receives the domain via a tRPC request. It validates the domain format using utilities from `packages/utility/src/urls.ts` and saves it to the database with a ‘pending’ status. 3. Backend - DNS Instruction Generation: The backend determines the required DNS records the user needs to add (e.g., an A record pointing to the hosting provider’s IP address). 4. Frontend - Display Instructions: The UI displays these DNS records to the user with clear, easy-to-follow instructions. 5. User Action (External): The user goes to their domain registrar (e.g., GoDaddy, Namecheap) and adds the provided DNS records. 6. Frontend - Verification Trigger: After adding the records, the user returns to Onlook and clicks the “Verify” button. 7. Backend - DNS Verification: The backend triggers a process to perform a DNS lookup for the user’s domain. It checks if the records match the required values. This may not be instant and can involve polling. 8. Backend - Activation: Once the DNS records are verified, the backend updates the domain’s status to ‘verified’ in the database and instructs the hosting provider to route traffic from the custom domain to the user’s deployment. User Display: The UI shows a “verified” status next to the domain name.
Comprehensive File System Management	User Intent: To have reliable, efficient management of all project files with automatic synchronization, conflict resolution, and performance optimization throughout the development process. End-to-End Flow: 1. System - Intelligent File Indexing: When a project is opened, the system performs comprehensive indexing of all project files, creating an organized catalog that includes file types, dependencies, and relationships between components. 2. Backend - Bidirectional Synchronization: The system maintains real-time synchronization between the local project state and the CodeSandbox environment, ensuring all changes are immediately reflected across all interfaces and tools. 3. System - File Change Detection and Handling: The system monitors all file changes (creation, modification, deletion, renaming) and automatically propagates these changes while maintaining project integrity and preventing conflicts. 4. Frontend - File Operation Interface: Users can perform file operations through multiple interfaces: the file browser in the left panel, direct code editing in the right panel, or visual operations through the canvas interface. Key Rules & Constraints: - All file operations must maintain project structure integrity and prevent breaking dependencies. - File synchronization must be efficient and handle large projects without performance degradation. - The system must provide clear feedback for file operations and handle errors gracefully.
GitHub Code Synchronization	User Intent: To have a complete, production-ready copy of their application’s codebase in their own GitHub repository for versioning, collaboration, or custom CI/CD pipelines. End-to-End Flow: 1. Frontend - Repository Connection: Users initiate GitHub synchronization through the project settings, with the system guiding them through GitHub App authorization if not already connected. 2. System - Repository Selection: After authorization, users can choose from their existing repositories or create a new repository specifically for the project, with the system providing recommendations based on project characteristics. 3. Backend - Code Preparation: The system prepares the complete project codebase for synchronization, including all source files, configuration files, and necessary documentation, while excluding development-specific files. 4. System - Repository Synchronization: The prepared code is committed and pushed to the selected GitHub repository with meaningful commit messages that describe the project state and changes. 5. Frontend - Sync Confirmation: Users receive confirmation of successful synchronization with direct links to the GitHub repository and information about what was synchronized. Key Rules & Constraints: - GitHub synchronization must preserve the complete project functionality and structure. - Commit messages must be descriptive and provide clear information about project changes. - The system must handle both initial repository creation and updates to existing repositories.

Technical Solution

Natural Language Technical Solution

The Deployment & Publishing system operates as a comprehensive project lifecycle management platform that seamlessly integrates project creation, file management, and publishing workflows through sophisticated backend orchestration and intelligent automation.

The Project Creation System supports multiple initiation pathways, each optimized for different user needs. AI-driven creation uses the same prompt hydration system as the code generation module to understand user intent and generate appropriate project structures. Local import processes files through validation pipelines that ensure Next.js compatibility while preserving project integrity. Template forking creates independent project copies through CodeSandbox duplication, maintaining complete isolation between template sources and user projects.

The File System Management operates through a sophisticated SandboxManager that maintains bidirectional synchronization between local project state and remote CodeSandbox environments. This system includes intelligent file indexing, real-time change detection, and conflict resolution mechanisms that ensure project integrity across all operations.

The Publishing Infrastructure uses an abstracted hosting provider interface that supports multiple deployment targets. The system automatically handles project packaging, dependency resolution, and deployment orchestration while providing users with simple, one-click publishing capabilities.

GitHub Integration operates through a secure GitHub App authentication flow that provides granular permissions for repository operations. The system can both import projects from GitHub repositories and synchronize completed projects back to user repositories, creating a complete development lifecycle that integrates with existing developer workflows.

End-to-end Execution Sequence Diagram (Project Creation to Publishing)

AI Replication & Reference

Deployment & Publishing Replication Guide

Prompt

You are an expert full-stack developer. Your task is to create a comprehensive project lifecycle management system that handles project creation, import, file management, and publishing for a web-based development platform.
 
**Core Feature: Complete Project Lifecycle Management**
 
**1. Project Creation and Import System:**
- Build multiple project initiation pathways: AI-driven creation, local import, template forking, and GitHub import
- Implement project validation pipelines that ensure Next.js compatibility and proper structure
- Create intelligent project name generation using AI for meaningful project identification
- Build template management system with forking capabilities and user favorites
 
**2. Comprehensive File System Management:**
- Implement SandboxManager class for bidirectional file synchronization with CodeSandbox
- Build intelligent file indexing system that catalogs file types, dependencies, and relationships
- Create real-time file change detection and propagation system
- Implement conflict resolution and error handling for file operations
 
**3. Project Dashboard and Organization:**
- Build visual project overview with thumbnails, metadata, and quick access
- Implement multiple sorting and filtering options (alphabetical, date, usage)
- Create real-time search functionality across project names, descriptions, and tags
- Build template integration with personal project management
 
**4. Publishing and Deployment Infrastructure:**
- Create abstracted hosting provider interface supporting multiple deployment targets
- Implement one-click publishing with automatic subdomain generation
- Build custom domain management with DNS verification workflows
- Create deployment health monitoring and error reporting systems
 
**5. GitHub Integration System:**
- Implement GitHub App authentication flow with granular permissions
- Build repository import capabilities for existing projects
- Create code synchronization system for pushing projects to GitHub
- Handle both repository creation and updates with meaningful commit messages
 
**6. Advanced File Operations:**
- Build file watching capabilities with event bus system for change notifications
- Implement batch file processing for large project operations
- Create file type detection and handling for various asset types
- Build caching system for performance optimization
 
**Technical Requirements:**
- **Frontend Framework:** Next.js with React and TypeScript for dashboard and editor interfaces
- **Backend API:** tRPC for type-safe API communication with comprehensive error handling
- **Database:** PostgreSQL with Drizzle ORM for project metadata and user associations
- **File Management:** CodeSandbox SDK for cloud development environments
- **GitHub Integration:** Octokit library with GitHub App authentication
- **Publishing:** Abstracted hosting provider interface (Freestyle, etc.)
- **State Management:** MobX for reactive project state management
 
**Acceptance Criteria:**
1. Users can create projects through multiple pathways (AI, import, template, GitHub)
2. File system operations maintain project integrity and provide real-time synchronization
3. Project dashboard provides efficient organization and search capabilities
4. Publishing workflows support both subdomain and custom domain deployment
5. GitHub integration handles both import and export operations seamlessly
6. All operations provide clear feedback and handle errors gracefully
7. System scales efficiently with large numbers of projects and files

Functional Role	Code File	Description
Project Dashboard Interface	`apps/web/client/src/app/projects/page.tsx`	Main project dashboard interface with project overview and management capabilities.
Project Selection and Organization	`apps/web/client/src/app/projects/_components/select/index.tsx`	Project selection interface with search, filtering, and organization features.
Project Creation Manager	`apps/web/client/src/components/store/create/manager.ts`	Core project creation logic handling AI-driven creation and GitHub import workflows.
Template System	`apps/web/client/src/app/projects/_components/templates/index.tsx`	Template browsing, selection, and forking system for project creation.
Template Forking Backend	`apps/web/client/src/server/api/routers/project/template.ts`	Backend logic for template forking and project duplication operations.
Local Import Interface	`apps/web/client/src/app/projects/import/local/page.tsx`	Local project import interface with file selection and validation.
Import Processing Context	`apps/web/client/src/app/projects/import/local/_context/index.tsx`	Project import processing logic with file validation and CodeSandbox integration.
File System Management	`apps/web/client/src/components/store/editor/sandbox/index.ts`	Comprehensive file system management with bidirectional synchronization and change detection.
File Synchronization	`apps/web/client/src/components/store/editor/sandbox/file-sync.ts`	File synchronization engine with caching, conflict resolution, and performance optimization.
Publishing Backend	`apps/web/client/src/server/api/routers/publish/index.ts`	Publishing and deployment API with hosting provider integration.
GitHub Integration	`packages/github/src/auth.ts`	GitHub authentication and repository operations for import and synchronization.
Hosting Provider Interface	`packages/models/src/hosting/index.ts`	Abstracted interface for different hosting backends enabling flexible deployment options.

Version Control User & Accounts