# htdangkhoa/headless-service architecture

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

- Interactive diagram: https://gitdiagram.com/htdangkhoa/headless-service
- Repository: https://github.com/htdangkhoa/headless-service

## Overview

##### Project type and purpose
- This is a backend micro-service (“Headless Service”) that exposes both an HTTP API and a WebSocket interface to let clients drive Puppeteer (headless browser) logic on the server side. It is not a traditional full-stack app with a UI, but rather a “Browser-as-a-Service” component.

##### File structure
- Top-level folders & files:
- docker/ – Dockerfiles per browser (Chrome, Brave) + startup scripts
- docs/ – design docs (CDP, Session Inspector, general description)
- examples/ – sample usage scripts (block-ads, demo, recorder, live, etc.)
- extensions/ – placeholder for extension artifacts
- public/docs/ – static docs site
- scripts/ – build & install helpers
- src/ – main TypeScript source
- Within src/:
- src/router/ + src/routes/ – HTTP & WS routing layers
- src/cdp/ – abstraction over CDP & Puppeteer Core, BrowserManager
- src/plugins/ – Puppeteer Extra plugins (ghostery, recorder, session…)
- src/shared/ – bundled browser extensions & live-stream client code
- src/utils/, src/constants/, src/schemas/ – supporting modules
- headless-server.ts + index.ts – bootstrap + server start

##### README for additional insights
- Exposes REST endpoints under /api/* for on-demand functions (screenshot, pdf, scrape, performance, generic code)
- Exposes WebSocket entrypoints for raw DevTools commands and live screencast
- Configurable by environment variables (HOST, PORT, SECRET, EXTENSIONS_PATH, etc.)
- Supports Docker images per browser

##### Detail without overthinking
- Every major folder/function group (router, cdp, plugins, shared/live, etc.)
- Illustration can be traced from incoming HTTP/WebSocket request all the way through to Puppeteer playback and response

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Clients"
        direction TB
        HTTPClient["HTTP Clients"]:::external
        WSClient["WebSocket Clients"]:::external
    end

    subgraph "Docker Container"
        direction TB

        subgraph "API Layer"
            direction TB
            HTTPRouter["HTTP Router"]:::api
            WSRouter["WebSocket Router"]:::api
        end

        subgraph "Controllers/Handlers"
            direction TB
            RESTHandlers["REST Handlers"]:::controller
            WSHandlers["WS Handlers"]:::controller
        end

        subgraph "Core Service Layer"
            direction TB
            BrowserManager["BrowserManager"]:::core
            CDPProxy["CDP DevTools Proxy"]:::core
            PluginManager["Plugin Manager"]:::core
            ExtensionInjector["Extension Injector"]:::core
        end

        subgraph "Puppeteer Core & Browser"
            direction TB
            PuppeteerCore["puppeteer-core & Browser Instances"]:::external
        end

        subgraph "Live/Screencast Module"
            direction TB
            LiveModule["Live Module"]:::core
        end

        Utils["Utilities & Config"]:::util
    end

    HTTPClient -->|REST request| HTTPRouter
    WSClient -->|WS request| WSRouter
    HTTPRouter -->|route| RESTHandlers
    WSRouter -->|route| WSHandlers
    RESTHandlers -->|invoke| BrowserManager
    WSHandlers -->|invoke| BrowserManager
    WSHandlers -->|CDP commands| CDPProxy
    BrowserManager -->|launch| PuppeteerCore
    BrowserManager -->|uses| PluginManager
    BrowserManager -->|inject| ExtensionInjector
    CDPProxy -->|forward CDP| PuppeteerCore
    PuppeteerCore -->|frames| LiveModule
    LiveModule -->|stream| WSClient
    Utils -->|config| HTTPRouter
    Utils -->|config| BrowserManager

    %% Click Events
    click HTTPRouter "https://github.com/htdangkhoa/headless-service/blob/main/src/router/http.route.ts"
    click WSRouter "https://github.com/htdangkhoa/headless-service/blob/main/src/router/ws.route.ts"
    click RESTHandlers "https://github.com/htdangkhoa/headless-service/tree/main/src/routes/api"
    click WSHandlers "https://github.com/htdangkhoa/headless-service/tree/main/src/routes/ws"
    click BrowserManager "https://github.com/htdangkhoa/headless-service/blob/main/src/cdp/browser-manager.ts"
    click CDPProxy "https://github.com/htdangkhoa/headless-service/blob/main/src/cdp/devtools/index.ts"
    click PluginManager "https://github.com/htdangkhoa/headless-service/tree/main/src/plugins"
    click ExtensionInjector "https://github.com/htdangkhoa/headless-service/tree/main/src/shared/extensions"
    click PuppeteerCore "https://github.com/htdangkhoa/headless-service/blob/main/src/cdp/index.ts"
    click LiveModule "https://github.com/htdangkhoa/headless-service/tree/main/src/shared/live"
    click Utils "https://github.com/htdangkhoa/headless-service/tree/main/src/utils"

    %% Styles
    classDef api fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef controller fill:#AFEEEE,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef util fill:#F0E68C,stroke:#333,stroke-width:1px
    classDef deploy fill:#D3D3D3,stroke:#333,stroke-width:1px
```
