# webstudio-is/webstudio architecture

> Architecture diagram of the GitHub repository webstudio-is/webstudio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/webstudio-is/webstudio
- Repository: https://github.com/webstudio-is/webstudio

## Overview

##### Main Components
- Frontend UI Applications – The “apps” directory (e.g. apps/builder, apps/dashboard, apps/canvas, etc.) represents the client-side interface. The builder’s UI (with components for authentication, project sharing, editing designs, asset management, and live preview) is a core visual component.
- Backend Services – Backend routes and servers are interwoven across the “apps” and “packages” folders. Look for service files under apps (like routes, services, auth and sync endpoints) and packages (e.g. authorization-token, postgrest, prisma-client, project, domain) which handle business logic, authentication, data sessions, and database operations.
- API & Data Layer – Modules under packages such as “prisma-client”, “postgrest”, “domain”, “dashboard”, “trpc-interface” indicate clear separation of data handling and API endpoints. These provide REST/TRPC interfaces for accessing the database and application resources.
- Asset & Media Management – Packages like “asset-uploader”, “image”, “css-engine”, “css-data” manage file uploads, image optimization, CSS processing, and design token transformation.
- AI & Automation – The “packages/ai” folder shows that there are functionalities for AI-driven chain responses (e.g. copywriting, command detection, template generation) which are an important part of the platform.
- CLI & SDK Tools – Several packages (cli, sdk, react-sdk, template, tsconfig, generate-arg-types) are used for developer tooling, scaffolding, and integration with external workflows.
- Infrastructure & DevOps – Directories such as “.devcontainer”, “.github”, “docker-compose.yml”, “vercel.json”, and numerous CI workflow YAML files indicate integration with containerization, testing, CI/CD, and deployment infrastructure.

##### Relationships and Interactions
- The Frontend (Builder UI, Dashboard, Canvas, etc.) communicates with the Backend APIs (via REST/TRPC endpoints) to retrieve user data, project information, assets, and design tokens.
- The Backend services – implemented with database clients (Prisma) and business logic modules – sit behind authentication (authorization-token, session, csfr, etc.) and serve requests made from the UI.
- Asset and media management modules interact with file storage solutions (via S3 or filesystem-based clients) to upload, retrieve, and optimize images and other assets.
- The AI modules work as independent services or microservices that interact with the core application—processing client requests, generating templates, and handling operations like style editing or copy changes.
- The CLI and SDK components are used by developers to generate and manage projects, glue together build tasks, and facilitate testing and deployment. They integrate with core platform services.

##### Architectural Patterns and Design Principles
- Modularity & Separation of Concerns: The monorepo structure clearly segments functionality (UI, API, asset management, CLI tools, etc.) into separate packages.
- Microservices/Multi-layered Architecture: Although they reside in one repository, the design suggests a service-oriented architecture where independent modules (authentication, assets, AI, etc.) interact via clearly defined APIs.
- Reusability & Componentization: A comprehensive design system and shared utility packages emphasize reuse, which is visible in many “packages/sdk-components…” and design-system folders.
- DevOps & CI/CD Integration: Embedded Docker and GitHub Actions configurations indicate that environment setup, testing, build pipelines, and deployment are important parts of the overall architecture.

##### Essential Elements
- Clear labels for each component (e.g., “Builder UI”, “Dashboard”, “API Gateway”, “Database/Prisma Client”, “Asset Uploader”, “AI Engine”, “CLI Tools”).

##### Final Advice
- Drill down into critical modules—especially the Builder application (with features like authentication, live editing, and asset management) and the backend API (with database connectivity, business logic, and TRPC interfaces).
- Since Webstudio is both a development platform and a visual builder, emphasize interactions between the visual editor, the code generation/templating modules, and backend processing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Applications
    subgraph "Frontend Applications"
        A["Builder UI"]:::frontend
        B["Dashboard UI"]:::frontend
        C["Canvas (Visual Editor)"]:::frontend
    end

    %% Backend Services & API Layer
    subgraph "Backend Services"
        D["API Routes & Endpoints"]:::backend
        E["Business Logic & Auth"]:::backend
        F["Prisma Client (Database)"]:::backend
        G["REST/TRPC Interfaces & Domain Logic"]:::backend
    end

    %% Asset & AI Services
    subgraph "Asset & AI Services"
        H["Asset Uploader & File Handler"]:::asset
        I["Image & CSS Processing"]:::asset
        J["AI Engine"]:::asset
    end

    %% CLI & SDK Tools
    subgraph "CLI & SDK Tools"
        K["CLI & Developer Tools"]:::cli
        L["SDK Libraries"]:::cli
    end

    %% Infrastructure & DevOps
    subgraph "Infrastructure & DevOps"
        M["Dev Containers"]:::devops
        N["CI/CD & Deployment Configuration"]:::devops
    end

    %% Shared Utilities & Design System
    subgraph "Shared Utilities & Design System"
        O["Design System & Reusable UI"]:::shared
        P["JSX Utilities & Icons"]:::shared
    end

    %% Connections: Frontend to Backend
    A -->|"requests"| D
    B -->|"requests"| D
    C -->|"requests"| D

    %% Backend processing and database interaction
    D -->|"uses"| E
    E -->|"connectsTo"| F
    D -->|"calls"| G

    %% Frontend interactions with Shared Utilities
    A -->|"uses"| O
    B -->|"uses"| O
    C -->|"uses"| O
    E -->|"uses"| P

    %% Asset & AI interactions
    A -->|"uploadsAssets"| H
    A -->|"requestsImages"| I
    E -->|"invokesAI"| J

    %% CLI & SDK integration with Backend
    K -->|"managesProjects"| E
    L -->|"integratesWith"| E

    %% Infrastructure supports Frontend and Backend
    M -->|"supports"| A
    M -->|"supports"| D
    N -->|"deploys"| A
    N -->|"deploys"| D

    %% Click Events
    click A "https://github.com/webstudio-is/webstudio/tree/main/apps/builder"
    click B "https://github.com/webstudio-is/webstudio/tree/main/apps/builder/app/dashboard"
    click C "https://github.com/webstudio-is/webstudio/tree/main/apps/builder/app/canvas"
    
    click D "https://github.com/webstudio-is/webstudio/tree/main/apps/builder/app/routes"
    click D "https://github.com/webstudio-is/webstudio/tree/main/apps/builder/app/services"
    
    click E "https://github.com/webstudio-is/webstudio/tree/main/packages/authorization-token"
    click E "https://github.com/webstudio-is/webstudio/tree/main/packages/trpc-interface"
    click E "https://github.com/webstudio-is/webstudio/tree/main/packages/project"
    click E "https://github.com/webstudio-is/webstudio/tree/main/packages/domain"
    
    click F "https://github.com/webstudio-is/webstudio/tree/main/packages/prisma-client"
    
    click G "https://github.com/webstudio-is/webstudio/tree/main/packages/postgrest"
    click G "https://github.com/webstudio-is/webstudio/tree/main/packages/trpc-interface"
    click G "https://github.com/webstudio-is/webstudio/tree/main/packages/domain"
    click G "https://github.com/webstudio-is/webstudio/tree/main/packages/dashboard"
    
    click H "https://github.com/webstudio-is/webstudio/tree/main/packages/asset-uploader"
    
    click I "https://github.com/webstudio-is/webstudio/tree/main/packages/image"
    click I "https://github.com/webstudio-is/webstudio/tree/main/packages/css-engine"
    click I "https://github.com/webstudio-is/webstudio/tree/main/packages/css-data"
    
    click J "https://github.com/webstudio-is/webstudio/tree/main/packages/ai"
    
    click K "https://github.com/webstudio-is/webstudio/tree/main/packages/cli"
    click K "https://github.com/webstudio-is/webstudio/tree/main/packages/sdk-cli"
    
    click L "https://github.com/webstudio-is/webstudio/tree/main/packages/sdk"
    click L "https://github.com/webstudio-is/webstudio/tree/main/packages/react-sdk"
    
    click M "https://github.com/webstudio-is/webstudio/blob/main/.devcontainer"
    
    click N "https://github.com/webstudio-is/webstudio/blob/main/.github"
    click N "https://github.com/webstudio-is/webstudio/blob/main/apps/builder/docker-compose.yaml"
    click N "https://github.com/webstudio-is/webstudio/blob/main/vercel.json"
    click N "https://github.com/webstudio-is/webstudio/blob/main/docker-compose.yml"
    
    click O "https://github.com/webstudio-is/webstudio/tree/main/packages/design-system"
    
    click P "https://github.com/webstudio-is/webstudio/tree/main/packages/jsx-utils"
    click P "https://github.com/webstudio-is/webstudio/tree/main/packages/icons"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef asset fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef cli fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef devops fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef shared fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
```
