docs/architecture.md

Architecture — one container, everything inside

Everything runs in one container built from the root Dockerfile. The extensions inside Chrome dial their servers on hardcoded 127.0.0.1 ports, so the servers must share Chrome's localhost — a separate machine/Space can never reach them. That's why there's a single image, not microservices.

            https://…hf.space   (only port 3001 is public)
                     │
            ┌────────▼─────────┐
            │ monitor :3001     │  UI + API gateway (one Go binary)
            │  /  /chrome.log   │  (open, no key)
            │  /gpt /gemini /flow│  (API-key gated → localhost)
            └──┬──────┬──────┬──┘
       9225 ───┘   8000│      └─── 8101
   (chatgpt)      (gemini)        (flow)
        │             │             │
   ws 9225       ws 9226       ws 9227     ◄── extensions dial in (localhost)
        └──────── Chrome (headless) + 3 unpacked extensions ────────┘
              CDP 9222  ·  socat proxy 9223  ·  profile in /home/chrome/data

Port map (all on the container's 127.0.0.1)

Port	Who	Purpose
3001	monitor	UI + API gateway (only published port)
9222	Chrome	DevTools Protocol (CDP)
9223	socat	CDP proxied for external tools
9225	chatgpt server	HTTP API and extension WS (same port)
8000 / 9226	gemini server	HTTP API / extension cookie-WS
8101 / 8100 / 9227	flow server	HTTP API / ext-callback / extension WS

What starts it

start_hf.sh (the container entrypoint) in order: restore profile from Postgres → clean profile → start monitor (3001) → CDP proxy → start the 3 backend servers (step 6a) → launch Chrome with the 3 extensions. Each server logs to /home/chrome/{chatgpt,gemini,flow}.log.

Components added on top of the base image

• monitor/ — Go UI, now also the reverse-proxy gateway (gatewayHandler, authOK).
• profilesync/ — Go tool, Chrome profile ⇄ Postgres snapshot.
• free-Chatgpt-api/, free-gemini-api/ (Go) + flow-agent/ (Python/FastAPI) — the 3 servers, built/installed into the image by the Dockerfile.