# muhammadusamamx/chrome-isolation architecture

> Architecture diagram of the GitHub repository muhammadusamamx/chrome-isolation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/muhammadusamamx/chrome-isolation
- Repository: https://github.com/muhammadusamamx/chrome-isolation

## Overview

Chrome Isolation Manager is a GNOME/Electron desktop app for creating and operating isolated Chrome profiles in Docker. The main workflow runs from profile management in the UI, through stdio JSON IPC and backend profile operations, to a per-profile container that launches Chromium. Supporting branches cover proxy management, safe profile import/export, and GNOME desktop entries. Edges reflect README documentation and shown source references; container-image internals are described in the README, but their implementation was not sampled.

Main entry points: [`backend/docker_manager.py`](https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/docker_manager.py) (Container lifecycle), [`backend/profile_service.py`](https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/profile_service.py) (Profile operations), [`Dockerfile`](https://github.com/muhammadusamamx/chrome-isolation/blob/main/Dockerfile) (Isolated Chrome image), [`backend/registry.py`](https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/registry.py) (Profile registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_renderer["Profile UI<br/>[app.js]"]
  node_preload["Secure API<br/>[preload.js]"]
  node_main["Electron main<br/>[main.js]"]
end

subgraph group_backend["Backend services"]
  node_bridge["Stdio bridge<br/>[bridge.py]"]
  node_service["Profile operations<br/>[profile_service.py]"]
  node_config["Path configuration<br/>[config.py]"]
  node_validator["Input validation<br/>[validator.py]"]
end

subgraph group_profile_data["Profile data"]
  node_registry[("Profile registry<br/>[registry.py]")]
  node_archive["Profile archives<br/>[archive.py]"]
  node_proxy_store[("Proxy store<br/>[proxy_store.py]")]
end

subgraph group_container["Container runtime"]
  node_docker_manager["Container lifecycle<br/>[docker_manager.py]"]
  node_image["Isolated Chrome image"]
  node_stealth["Stealth launch<br/>[stealth-launch.sh]"]
  node_hardware["Hardware fingerprint<br/>[hardware-spoof.sh]"]
  node_user_agent["User-agent spoofing"]
  node_proxy_wrapper["Proxy auth wrapper<br/>[proxy-wrapper.py]"]
end

subgraph group_integrations["Integrations"]
  node_desktop_manager["GNOME entries<br/>[desktop_manager.py]"]
  node_docker[("Docker daemon")]
  node_host["Host desktop"]
end

node_user(("User"))

node_user -->|"uses"| node_renderer
node_renderer -->|"calls API"| node_preload
node_preload -->|"forwards IPC"| node_main
node_main -->|"sends JSON"| node_bridge
node_bridge -->|"dispatches"| node_service
node_bridge -->|"dispatches"| node_proxy_store
node_service -->|"manages profiles"| node_registry
node_service -->|"controls lifecycle"| node_docker_manager
node_service -->|"imports/exports"| node_archive
node_service -->|"manages entries"| node_desktop_manager
node_service -->|"validates inputs"| node_validator
node_docker_manager -->|"reads profile"| node_registry
node_docker_manager -->|"resolves proxy"| node_proxy_store
node_docker_manager -->|"starts containers"| node_docker
node_docker_manager -->|"runs image"| node_image
node_image -->|"starts with"| node_stealth
node_image -->|"configures fingerprint"| node_hardware
node_image -->|"sets user-agent"| node_user_agent
node_docker_manager -->|"uses for auth"| node_proxy_wrapper
node_docker_manager -->|"mounts preferences"| node_host
node_archive -->|"registers import"| node_registry
node_archive -->|"validates names"| node_validator
node_desktop_manager -->|"validates names"| node_validator
node_registry -->|"validates paths"| node_validator
node_proxy_wrapper -.->|"runs in container"| node_docker

click node_renderer "https://github.com/muhammadusamamx/chrome-isolation/blob/main/electron/renderer/app.js"
click node_preload "https://github.com/muhammadusamamx/chrome-isolation/blob/main/electron/preload.js"
click node_main "https://github.com/muhammadusamamx/chrome-isolation/blob/main/electron/main.js"
click node_bridge "https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/bridge.py"
click node_service "https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/profile_service.py"
click node_config "https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/config.py"
click node_validator "https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/validator.py"
click node_registry "https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/registry.py"
click node_archive "https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/archive.py"
click node_proxy_store "https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/proxy_store.py"
click node_docker_manager "https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/docker_manager.py"
click node_image "https://github.com/muhammadusamamx/chrome-isolation/blob/main/Dockerfile"
click node_stealth "https://github.com/muhammadusamamx/chrome-isolation/blob/main/scripts/docker/stealth-launch.sh"
click node_hardware "https://github.com/muhammadusamamx/chrome-isolation/blob/main/scripts/docker/hardware-spoof.sh"
click node_user_agent "https://github.com/muhammadusamamx/chrome-isolation/blob/main/scripts/docker/user-agent-spoof.sh"
click node_proxy_wrapper "https://github.com/muhammadusamamx/chrome-isolation/blob/main/scripts/docker/proxy-wrapper.py"
click node_desktop_manager "https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/desktop_manager.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_renderer,node_preload,node_main,node_user toneBlue
class node_bridge,node_service,node_config,node_validator toneAmber
class node_registry,node_archive,node_proxy_store toneMint
class node_docker_manager,node_image,node_stealth,node_hardware,node_user_agent,node_proxy_wrapper toneRose
class node_desktop_manager,node_docker,node_host toneIndigo
```

## Components

### Desktop app

- [Profile UI](https://github.com/muhammadusamamx/chrome-isolation/blob/main/electron/renderer/app.js): `electron/renderer/app.js`
- [Secure API](https://github.com/muhammadusamamx/chrome-isolation/blob/main/electron/preload.js): `electron/preload.js`
- [Electron main](https://github.com/muhammadusamamx/chrome-isolation/blob/main/electron/main.js): `electron/main.js`

### Backend services

- [Stdio bridge](https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/bridge.py): `backend/bridge.py`
- [Profile operations](https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/profile_service.py): `backend/profile_service.py`
- [Path configuration](https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/config.py): `backend/config.py`
- [Input validation](https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/validator.py): `backend/validator.py`

### Profile data

- [Profile registry](https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/registry.py): `backend/registry.py`
- [Profile archives](https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/archive.py): `backend/archive.py`
- [Proxy store](https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/proxy_store.py): `backend/proxy_store.py`

### Container runtime

- [Container lifecycle](https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/docker_manager.py): `backend/docker_manager.py`
- [Isolated Chrome image](https://github.com/muhammadusamamx/chrome-isolation/blob/main/Dockerfile): `Dockerfile`
- [Stealth launch](https://github.com/muhammadusamamx/chrome-isolation/blob/main/scripts/docker/stealth-launch.sh): `scripts/docker/stealth-launch.sh`
- [Hardware fingerprint](https://github.com/muhammadusamamx/chrome-isolation/blob/main/scripts/docker/hardware-spoof.sh): `scripts/docker/hardware-spoof.sh`
- [User-agent spoofing](https://github.com/muhammadusamamx/chrome-isolation/blob/main/scripts/docker/user-agent-spoof.sh): `scripts/docker/user-agent-spoof.sh`
- [Proxy auth wrapper](https://github.com/muhammadusamamx/chrome-isolation/blob/main/scripts/docker/proxy-wrapper.py): `scripts/docker/proxy-wrapper.py`

### Integrations

- [GNOME entries](https://github.com/muhammadusamamx/chrome-isolation/blob/main/backend/desktop_manager.py): `backend/desktop_manager.py`
- **Docker daemon**
- **Host desktop**

### Other components

- **User**

## Connections

- User → Profile UI: uses (evidence: `README.md`)
- Profile UI → Secure API: calls API (evidence: `README.md`)
- Secure API → Electron main: forwards IPC (evidence: `README.md`)
- Electron main → Stdio bridge: sends JSON (evidence: `README.md`)
- Stdio bridge → Profile operations: dispatches (evidence: `backend/bridge.py`)
- Stdio bridge → Proxy store: dispatches (evidence: `backend/bridge.py`)
- Profile operations → Profile registry: manages profiles (evidence: `backend/profile_service.py`)
- Profile operations → Container lifecycle: controls lifecycle (evidence: `backend/profile_service.py`)
- Profile operations → Profile archives: imports/exports (evidence: `backend/profile_service.py`)
- Profile operations → GNOME entries: manages entries (evidence: `backend/profile_service.py`)
- Profile operations → Input validation: validates inputs (evidence: `backend/profile_service.py`)
- Container lifecycle → Profile registry: reads profile (evidence: `backend/docker_manager.py`)
- Container lifecycle → Proxy store: resolves proxy (evidence: `backend/docker_manager.py`)
- Container lifecycle → Docker daemon: starts containers (evidence: `README.md`)
- Container lifecycle → Isolated Chrome image: runs image (evidence: `README.md`)
- Isolated Chrome image → Stealth launch: starts with (evidence: `README.md`)
- Isolated Chrome image → Hardware fingerprint: configures fingerprint (evidence: `README.md`)
- Isolated Chrome image → User-agent spoofing: sets user-agent (evidence: `README.md`)
- Container lifecycle → Proxy auth wrapper: uses for auth (evidence: `README.md`)
- Container lifecycle → Host desktop: mounts preferences (evidence: `README.md`)
- Profile archives → Profile registry: registers import (evidence: `backend/archive.py`)
- Profile archives → Input validation: validates names (evidence: `backend/archive.py`)
- GNOME entries → Input validation: validates names (evidence: `backend/desktop_manager.py`)
- Profile registry → Input validation: validates paths (evidence: `backend/registry.py`)
- Proxy auth wrapper → Docker daemon: runs in container
