docs/architecture/system-charts.md

System Charts

This page collects the main high-level charts for the current PinchTab architecture.

Chart 1: Product Shape

flowchart TD
    U["Agent / CLI / Tool"] --> S["PinchTab Server"]

    S --> D["Dashboard + Config + Profiles API"]
    S --> O["Orchestrator + Strategy Layer"]

    O --> M1["Managed Instance"]
    O --> M2["Managed Instance"]

    M1 --> B1["pinchtab bridge"]
    M2 --> B2["pinchtab bridge"]

    B1 --> C1["Chrome"]
    B2 --> C2["Chrome"]

    C1 --> T1["Tabs"]
    C2 --> T2["Tabs"]

    S -. "advanced attach path" .-> E["Registered External Chrome"]

This is the default system shape today:

• agents talk to the server over HTTP
• the server manages profiles, instances, and routing
• managed instances are bridge-backed
• attach exists as an advanced external-browser registration path

Chart 2: Primary Usage Path

flowchart LR
    I["Install PinchTab"] --> R["Run: pinchtab"]
    R --> L["Local server on localhost:9867"]
    L --> A["Agent / CLI sends HTTP requests"]
    A --> W["Browser work happens through PinchTab"]

This is the normal mental model for users. Most users should think about pinchtab, not pinchtab bridge.

Chart 3: Runtime Shapes

flowchart LR
    subgraph S1["Server Mode"]
        C1["Client"] --> P1["pinchtab server"]
        P1 --> B1["pinchtab bridge"]
        B1 --> CH1["Chrome"]
        CH1 --> T1["Tabs"]
    end

    subgraph S2["Bridge Mode"]
        C2["Client"] --> B2["pinchtab bridge"]
        B2 --> CH2["Chrome"]
        CH2 --> T2["Tabs"]
    end

Meaning:

• server mode is the multi-instance control-plane path
• bridge mode is the single-instance browser runtime

Chart 4: Current Request Paths

flowchart TD
    R["HTTP Request"] --> M["Auth + Middleware"]
    M --> T{"Route Type"}

    T -->|Direct browser route| X["Tab / Instance Resolution"]
    T -->|Task route, when enabled| Q["Scheduler"]
    T -->|Attach route| A["Attach Policy Check"]

    Q --> X
    X --> H["Bridge Handler"]
    H --> P["Handler-Level Policy Checks"]
    P --> C["Chrome via CDP"]
    C --> O["JSON / Text / PDF / Image Response"]

    A --> AR["Register External Instance"]

Important details:

• auth and shared middleware run at the HTTP layer
• attach policy is enforced on the attach route in the server
• IDPI and similar browser-facing checks run in handlers such as navigation, text, and snapshot
• tab-scoped routes are resolved to the owning instance before execution
• the scheduler is optional, server-only, and applies to /tasks
• bridge handlers perform the actual browser work