# automattic/studio architecture

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

- Interactive diagram: https://gitdiagram.com/automattic/studio
- Repository: https://github.com/automattic/studio

## Overview

##### Project type and purpose
- This is a desktop application built on Electron (Node.js + Chromium) with a React/TypeScript renderer and a companion CLI tool.
- Purpose: allow developers to spin up local WordPress environments, manage sites, snapshots, imports/exports, and connect to WordPress.com/Playground.

##### Main architectural components
A. Electron-based Desktop App
1. Main Process (Node.js)
– Files: src/main-window.ts, src/menu.ts, src/site-server.ts, src/ipc-handlers.ts, lib/…
– Responsibilities:
- Orchestrate local WordPress server processes (PHP + WP-CLI child processes)
- Manage file system (import/export, snapshots)
- Host a built-in proxy server for preview sites
- Handle IPC requests from the renderer
- Read/write user data (src/storage, JSON/SQLite)
2. Preload Script
– File: src/preload.ts
– Exposes a safe IPC bridge (window.api) to the renderer
3. Renderer Process (React + Redux + Hooks)
– Files under src/components, src/hooks, src/stores
– Responsibilities:
- Present the UI (site list, settings, snapshot manager, previews, “what’s new” modal)
- Dispatch IPC calls via the preload bridge
- Manage local state/slices and caching layers (Redux slices, offline checks)
B. Shared Libraries & Modules
– common/lib, src/lib, src/modules
– Provide utilities (fs-utils, OAuth, locale, sanitization), import/export workflows, preview-site module, site-settings & user-settings modules
C. CLI Tool
– Directory: cli/
– Entry: cli/index.ts, bin/studio-cli.sh/.bat
– Implements “studio preview create/list/delete/update” commands, uses cli/lib/api.ts to talk to WordPress.com APIs
– Shares common/lib code via workspace linking
D. External Services
– WordPress.com REST API (wpcom-api.ts in src/stores)
– WordPress Playground for sandboxed environments
– OAuth endpoints (common/lib/oauth, src/lib/oauth)
E. Packaging & CI/CD
– Build scripts: .buildkite/, fastlane/, scripts/*.mjs
– Outputs: macOS .dmg/.appx, Windows installers, bundled Electron binary

##### Relationships & data flows
- Main → Child Processes: spawn of local PHP + WP-CLI (site provisioning, import/export)
- Main ↔ Local Storage: read/write JSON or SQLite via storage/user-data.ts
- Main ↔ Proxy Server: intercept preview site traffic
- CLI → External APIs: HTTP calls to WordPress.com, returns JSON
- Renderer ↔ Redux Slices: local data access, offline caching, live UI updates

##### Key architectural patterns & design principles
– Electron multi-process model: strict separation of UI (renderer) and OS-level operations (main)
– Module decomposition: domain-specific modules (preview-site, site-settings, user-settings)
– Shared utility libraries: DRY approach across CLI and Desktop
– Import/export pipeline: event-driven workflow managers, pluggable importers/exporters
– Redux for state management + React hooks for UI logic

- Labels for each component (e.g., “Electron Main Process”, “React Renderer Process”, “CLI Executable”)
- Callouts for key framework/tech (Electron, React/TSX, Redux slices, Node.js child_process, SQLite/JSON, Fastlane/Buildkite)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Electron Main Process
    subgraph "Electron Main Process" 
        direction TB
        MP_Main["Main Process\n(Node.js)"]:::main
        MP_Menu["Menu Handler"]:::main
        MP_SiteServer["Site Server"]:::main
        MP_IPC["IPC Handlers"]:::main
        MP_Proxy["Proxy Server"]:::main
        MP_SSP["Site Server Process"]:::main
        MP_SSPChild["Site Server Child Process"]:::main
        MP_StorageLink["User Data Storage"]:::storage
    end

    %% Preload Script
    subgraph "Preload Script"
        direction TB
        Preload["Preload Bridge"]:::preload
    end

    %% Renderer Process
    subgraph "Renderer Process\n(React + Redux)" 
        direction TB
        RN_Index["Entry Point"]:::frontend
        RN_Components["UI Components"]:::frontend
        RN_Hooks["React Hooks"]:::frontend
        RN_Stores["Redux Stores"]:::frontend
    end

    %% Shared Libraries & Utilities
    subgraph "Shared Libraries & Utilities"
        direction TB
        SL_Common["common/lib"]:::shared
        SL_Lib["src/lib"]:::shared
        SL_FS["fs-utils"]:::shared
        SL_OAuth["oauth modules"]:::shared
        SL_ImportExport["import-export"]:::shared
        SL_PreviewMod["preview-site module"]:::shared
        SL_SiteSettings["site-settings module"]:::shared
        SL_UserSettings["user-settings module"]:::shared
        SL_WhatsNew["whats-new module"]:::shared
    end

    %% CLI Tool
    subgraph "CLI Tool"
        direction TB
        CLI_Main["cli/index.ts"]:::cli
        CLI_Create["preview create"]:::cli
        CLI_List["preview list"]:::cli
        CLI_Update["preview update"]:::cli
        CLI_Delete["preview delete"]:::cli
        CLI_API["CLI API client"]:::cli
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Ext_WPCOM["WordPress.com REST API"]:::external
        Ext_Play["WordPress Playground"]:::external
        Ext_OAuth["OAuth Endpoints"]:::external
    end

    %% Storage
    subgraph "Local Storage"
        direction TB
        DB_JSON["JSON/SQLite Storage"]:::storage
    end

    %% Connections
    RN_Components -->|"dispatch IPC"| MP_IPC
    RN_Stores -->|"read/write"| DB_JSON
    Preload -->|"exposes API"| RN_Components
    MP_IPC -->|"invoke"| MP_Main
    MP_Main -->|"spawn PHP server"| MP_SSP
    MP_SSP -->|"spawn WP-CLI"| MP_SSPChild
    MP_Main -->|"start proxy"| MP_Proxy
    MP_Main -->|"read/write"| DB_JSON
    CLI_Create -->|"HTTP REST"| Ext_WPCOM
    CLI_List -->|"HTTP REST"| Ext_WPCOM
    CLI_Update -->|"HTTP REST"| Ext_WPCOM
    CLI_Delete -->|"HTTP REST"| Ext_WPCOM
    CLI_API -->|"calls"| Ext_WPCOM
    SL_Common --> MP_Main
    SL_Lib --> MP_Main
    SL_Common --> CLI_Main
    SL_OAuth --> Ext_OAuth
    Ext_WPCOM --> CLI_Main
    SL_FS --> MP_Main
    SL_ImportExport --> MP_Main
    SL_PreviewMod --> MP_Main
    SL_SiteSettings --> MP_Main
    SL_UserSettings --> MP_Main
    SL_WhatsNew --> RN_Components

    %% Click Events - Electron Main Process
    click MP_Main "https://github.com/automattic/studio/blob/trunk/src/main-window.ts"
    click MP_Menu "https://github.com/automattic/studio/blob/trunk/src/menu.ts"
    click MP_SiteServer "https://github.com/automattic/studio/blob/trunk/src/site-server.ts"
    click MP_IPC "https://github.com/automattic/studio/blob/trunk/src/ipc-handlers.ts"
    click MP_SSP "https://github.com/automattic/studio/blob/trunk/src/lib/site-server-process.ts"
    click MP_SSPChild "https://github.com/automattic/studio/blob/trunk/src/lib/site-server-process-child.ts"
    click MP_Proxy "https://github.com/automattic/studio/blob/trunk/src/lib/proxy-server.ts"
    click MP_StorageLink "https://github.com/automattic/studio/blob/trunk/src/storage/user-data.ts"
    %% Also storage paths
    click DB_JSON "https://github.com/automattic/studio/blob/trunk/src/storage/paths.ts"

    %% Click Events - Preload
    click Preload "https://github.com/automattic/studio/blob/trunk/src/preload.ts"

    %% Click Events - Renderer
    click RN_Index "https://github.com/automattic/studio/blob/trunk/src/index.ts"
    click RN_Components "https://github.com/automattic/studio/tree/trunk/src/components/"
    click RN_Hooks "https://github.com/automattic/studio/tree/trunk/src/hooks/"
    click RN_Stores "https://github.com/automattic/studio/tree/trunk/src/stores/"
    click RN_Index "https://github.com/automattic/studio/blob/trunk/webpack.renderer.config.ts"
    click RN_Index "https://github.com/automattic/studio/blob/trunk/src/index.ejs"

    %% Click Events - Shared Libraries
    click SL_Common "https://github.com/automattic/studio/tree/trunk/common/lib/"
    click SL_Lib "https://github.com/automattic/studio/tree/trunk/src/lib/"
    click SL_FS "https://github.com/automattic/studio/blob/trunk/src/lib/fs-utils.ts"
    click SL_OAuth "https://github.com/automattic/studio/blob/trunk/src/lib/oauth.ts"
    click SL_ImportExport "https://github.com/automattic/studio/tree/trunk/src/lib/import-export/"
    click SL_PreviewMod "https://github.com/automattic/studio/tree/trunk/src/modules/preview-site/"
    click SL_SiteSettings "https://github.com/automattic/studio/tree/trunk/src/modules/site-settings/"
    click SL_UserSettings "https://github.com/automattic/studio/tree/trunk/src/modules/user-settings/"
    click SL_WhatsNew "https://github.com/automattic/studio/tree/trunk/src/modules/whats-new/"

    %% Click Events - CLI Tool
    click CLI_Main "https://github.com/automattic/studio/blob/trunk/cli/index.ts"
    click CLI_Create "https://github.com/automattic/studio/blob/trunk/cli/commands/preview/create.ts"
    click CLI_List "https://github.com/automattic/studio/blob/trunk/cli/commands/preview/list.ts"
    click CLI_Update "https://github.com/automattic/studio/blob/trunk/cli/commands/preview/update.ts"
    click CLI_Delete "https://github.com/automattic/studio/blob/trunk/cli/commands/preview/delete.ts"
    click CLI_API "https://github.com/automattic/studio/blob/trunk/cli/lib/api.ts"

    %% Click Events - External and CI/CD not mapped to files beyond above

    %% Styles
    classDef main fill:#8ecae6,stroke:#219ebc,color:#023047;
    classDef preload fill:#ffb703,stroke:#fb8500,color:#370617;
    classDef frontend fill:#a2d2ff,stroke:#1d3557,color:#000;
    classDef shared fill:#caf0f8,stroke:#0077b6,color:#000;
    classDef cli fill:#ffd6a5,stroke:#fb5607,color:#000;
    classDef external fill:#e9ecef,stroke:#adb5bd,color:#000;
    classDef storage fill:#d8f3dc,stroke:#40916c,color:#000;
```
