How htdangkhoa/headless-service works
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