docs/architecture/instance-charts.md

Instance Charts

This page captures the current instance model in PinchTab.

It is intentionally limited to the instance types and relationships that exist now in the codebase.

Chart 1: Current Instance Types

flowchart TD
    I["Instance"] --> M["Managed"]
    I --> A["Attached"]

    M --> MB["Bridge-backed"]
    A --> EX["External Chrome registration"]

Current meaning:

• managed means PinchTab launches and owns the runtime lifecycle
• attached means PinchTab registers an already running external Chrome
• bridge-backed means the server reaches the browser through a pinchtab bridge runtime

Chart 2: Managed Instance Shape

flowchart LR
    S["PinchTab Server"] --> O["Orchestrator"]
    O --> B["pinchtab bridge child"]
    B --> C["Chrome"]
    C --> T["Tabs"]
    O --> P["Profile directory"]

For managed instances today:

• the orchestrator launches a bridge child process
• the bridge owns one browser runtime
• tabs live inside that runtime
• browser state is tied to the associated profile directory

Chart 3: Attached Instance Shape

flowchart LR
    S["PinchTab Server"] --> O["Orchestrator"]
    O -. "attach via CDP URL" .-> E["External Chrome"]
    E --> T["Tabs"]

For attached instances today:

• PinchTab does not launch the browser
• PinchTab stores registration metadata in the instance registry
• ownership of the external browser process stays outside PinchTab
• attached registration exists today, but the normal managed-instance tab proxy path is still centered on bridge-backed instances

Chart 4: Ownership Model

flowchart TD
    I["Instance"] --> L["Lifecycle owner"]

    L --> P["PinchTab"]
    L --> X["External process owner"]

    P --> M["Managed instance"]
    X --> A["Attached instance"]

This is the key distinction:

• managed instances are lifecycle-owned by PinchTab
• attached instances are tracked by PinchTab but not process-owned by PinchTab

Chart 5: Routing Relationship

flowchart TD
    I["Instance"] --> T["Tabs"]
    T --> R["Tab-scoped routes"]
    R --> O["Owning instance resolution"]

The important runtime rule is:

• tabs belong to one instance
• for managed bridge-backed instances, tab-scoped server routes are resolved to the owning instance before proxying

Current Instance Fields

The main instance fields surfaced by the current API are:

• id
• profileId
• profileName
• port
• headless
• status
• startTime
• error
• attached
• cdpUrl

Useful interpretation:

• attached: false usually means a managed bridge-backed instance
• attached: true means an externally registered instance
• port is relevant for managed bridge-backed instances
• cdpUrl is relevant for attached instances