# cloakhq/cloakbrowser-manager architecture

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

- Interactive diagram: https://gitdiagram.com/cloakhq/cloakbrowser-manager
- Repository: https://github.com/cloakhq/cloakbrowser-manager

## Overview

CloakBrowser Manager is a self-hosted browser-profile manager: users organize isolated browser identities, configure per-profile fingerprint, network, locale, and compatibility options, then launch, view, and automate those sessions. The React UI calls a FastAPI service; the service coordinates profile persistence and browser lifecycle, with Linux sessions additionally served through KasmVNC and the web viewer. Settings and status expose licensing and runtime information. README-documented capabilities are included where their implementation is not shown; edges are limited to wiring supported by the sampled source.

Main entry points: [`frontend/src/App.tsx`](https://github.com/cloakhq/cloakbrowser-manager/blob/main/frontend/src/App.tsx) (Dashboard), [`backend/main.py`](https://github.com/cloakhq/cloakbrowser-manager/blob/main/backend/main.py) (REST and WebSockets), [`frontend/src/lib/api.ts`](https://github.com/cloakhq/cloakbrowser-manager/blob/main/frontend/src/lib/api.ts) (API client), [`frontend/src/components/ProfileViewer.tsx`](https://github.com/cloakhq/cloakbrowser-manager/blob/main/frontend/src/components/ProfileViewer.tsx) (Session viewer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Manager UI"]
  node_app["Dashboard<br/>[App.tsx]"]
  node_profile_ui["Profile editor<br/>[ProfileForm.tsx]"]
  node_profile_viewer["Session viewer<br/>[ProfileViewer.tsx]"]
  node_profiles_hook["Profile state<br/>[useProfiles.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_service["Backend service"]
  node_fastapi["REST and WebSockets<br/>[main.py]"]
  node_settings_store["Manager settings<br/>[settings_store.py]"]
end

subgraph group_profiles["Profile lifecycle"]
  node_profile_store["Profile persistence<br/>[database.py]"]
  node_sqlite[("Profile database")]
end

subgraph group_runtime["Browser runtime"]
  node_browser_manager["Browser lifecycle<br/>[browser_manager.py]"]
  node_runtime_config["Runtime detection<br/>[runtime.py]"]
  node_vnc_manager["VNC lifecycle<br/>[vnc_manager.py]"]
end

node_user(("User"))
node_cloak_engine["CloakBrowser engine"]
node_kasm["KasmVNC server"]
node_cdp_client["Playwright / Puppeteer"]

node_user -->|"uses"| node_app
node_app -->|"manages profiles"| node_profiles_hook
node_app -->|"edits profile"| node_profile_ui
node_app -->|"views session"| node_profile_viewer
node_app -->|"requests status"| node_api_client
node_profiles_hook -->|"requests profile actions"| node_api_client
node_profile_ui -->|"tests proxy"| node_api_client
node_api_client -->|"HTTP / WebSocket"| node_fastapi
node_profile_viewer -->|"syncs clipboard"| node_api_client
node_fastapi -->|"reads and writes"| node_profile_store
node_profile_store -->|"persists profiles"| node_sqlite
node_fastapi -->|"launches and stops"| node_browser_manager
node_browser_manager -->|"resolves runtime"| node_runtime_config
node_browser_manager -->|"launches browser"| node_cloak_engine
node_browser_manager -->|"starts display"| node_vnc_manager
node_vnc_manager -->|"starts Xvnc"| node_kasm
node_profile_viewer -->|"opens VNC session"| node_fastapi
node_profile_viewer -.->|"offers CDP endpoint"| node_cdp_client
node_fastapi -->|"loads settings"| node_settings_store

click node_app "https://github.com/cloakhq/cloakbrowser-manager/blob/main/frontend/src/App.tsx"
click node_profile_ui "https://github.com/cloakhq/cloakbrowser-manager/blob/main/frontend/src/components/ProfileForm.tsx"
click node_profile_viewer "https://github.com/cloakhq/cloakbrowser-manager/blob/main/frontend/src/components/ProfileViewer.tsx"
click node_profiles_hook "https://github.com/cloakhq/cloakbrowser-manager/blob/main/frontend/src/hooks/useProfiles.ts"
click node_api_client "https://github.com/cloakhq/cloakbrowser-manager/blob/main/frontend/src/lib/api.ts"
click node_fastapi "https://github.com/cloakhq/cloakbrowser-manager/blob/main/backend/main.py"
click node_profile_store "https://github.com/cloakhq/cloakbrowser-manager/blob/main/backend/database.py"
click node_browser_manager "https://github.com/cloakhq/cloakbrowser-manager/blob/main/backend/browser_manager.py"
click node_runtime_config "https://github.com/cloakhq/cloakbrowser-manager/blob/main/backend/runtime.py"
click node_vnc_manager "https://github.com/cloakhq/cloakbrowser-manager/blob/main/backend/vnc_manager.py"
click node_settings_store "https://github.com/cloakhq/cloakbrowser-manager/blob/main/backend/settings_store.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_profile_ui,node_profile_viewer,node_profiles_hook,node_api_client,node_user,node_cloak_engine toneBlue
class node_fastapi,node_settings_store toneAmber
class node_profile_store,node_sqlite,node_kasm toneMint
class node_browser_manager,node_runtime_config,node_vnc_manager toneRose
class node_cdp_client toneIndigo
```

## Components

### Manager UI

- [Dashboard](https://github.com/cloakhq/cloakbrowser-manager/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Profile editor](https://github.com/cloakhq/cloakbrowser-manager/blob/main/frontend/src/components/ProfileForm.tsx): `frontend/src/components/ProfileForm.tsx`
- [Session viewer](https://github.com/cloakhq/cloakbrowser-manager/blob/main/frontend/src/components/ProfileViewer.tsx): `frontend/src/components/ProfileViewer.tsx`
- [Profile state](https://github.com/cloakhq/cloakbrowser-manager/blob/main/frontend/src/hooks/useProfiles.ts): `frontend/src/hooks/useProfiles.ts`
- [API client](https://github.com/cloakhq/cloakbrowser-manager/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Backend service

- [REST and WebSockets](https://github.com/cloakhq/cloakbrowser-manager/blob/main/backend/main.py): `backend/main.py`
- [Manager settings](https://github.com/cloakhq/cloakbrowser-manager/blob/main/backend/settings_store.py): `backend/settings_store.py`

### Profile lifecycle

- [Profile persistence](https://github.com/cloakhq/cloakbrowser-manager/blob/main/backend/database.py): `backend/database.py`
- **Profile database**

### Browser runtime

- [Browser lifecycle](https://github.com/cloakhq/cloakbrowser-manager/blob/main/backend/browser_manager.py): `backend/browser_manager.py`
- [Runtime detection](https://github.com/cloakhq/cloakbrowser-manager/blob/main/backend/runtime.py): `backend/runtime.py`
- [VNC lifecycle](https://github.com/cloakhq/cloakbrowser-manager/blob/main/backend/vnc_manager.py): `backend/vnc_manager.py`

### Other components

- **User**
- **CloakBrowser engine**
- **KasmVNC server**
- **Playwright / Puppeteer**

## Connections

- User → Dashboard: uses
- Dashboard → Profile state: manages profiles
- Dashboard → Profile editor: edits profile
- Dashboard → Session viewer: views session
- Dashboard → API client: requests status
- Profile state → API client: requests profile actions
- Profile editor → API client: tests proxy
- API client → REST and WebSockets: HTTP / WebSocket
- Session viewer → API client: syncs clipboard
- REST and WebSockets → Profile persistence: reads and writes
- Profile persistence → Profile database: persists profiles
- REST and WebSockets → Browser lifecycle: launches and stops
- Browser lifecycle → Runtime detection: resolves runtime
- Browser lifecycle → CloakBrowser engine: launches browser
- Browser lifecycle → VNC lifecycle: starts display
- VNC lifecycle → KasmVNC server: starts Xvnc
- Session viewer → REST and WebSockets: opens VNC session
- Session viewer → Playwright / Puppeteer: offers CDP endpoint
- REST and WebSockets → Manager settings: loads settings