Skip to content

docs(architecture): document the PTY-on-Apps reference architecture#166

Open
jamesbroadhead wants to merge 1 commit into
datasciencemonkey:mainfrom
jamesbroadhead:jb/pty-on-apps-reference-doc
Open

docs(architecture): document the PTY-on-Apps reference architecture#166
jamesbroadhead wants to merge 1 commit into
datasciencemonkey:mainfrom
jamesbroadhead:jb/pty-on-apps-reference-doc

Conversation

@jamesbroadhead
Copy link
Copy Markdown

@jamesbroadhead jamesbroadhead commented May 27, 2026

Summary

CODA's PTY + Socket.IO + xterm.js + PAT-rotation + workspace-sync stack is novel infrastructure. It's currently only documented inside the design docs under docs/plans/ — fine for an archaeologist, less so for someone evaluating whether to build a similar product. This PR adds a single reference-architecture write-up that pulls the layers together and points at the relevant existing design docs.

Why

Each component (PTY allocation, transport fallback, PAT auto-rotation, workspace sync, single-user gate, single-worker gunicorn constraint) has its own design doc. None of them stand alone — they all interact, and the reasons the stack chose pty.openpty() over subprocess.Popen / tmux, why gunicorn is pinned to one worker, why .git/ can't go through import-dir, etc. are scattered across years of plans.

If "hosted agent in the browser" becomes a pattern more projects need on Databricks Apps, this stack is the reference implementation. Other implementers will re-derive the same trade-offs unless the answers are easy to find in one place.

Changes

  • docs/architecture/pty-on-apps.md — new file. Per-layer notes with rationale + caveats:
    • PTY allocation: pty.openpty() + os.fork() over subprocess.Popen (TUI escape codes); single-worker gunicorn (PTY fds are process-local).
    • Transport: Flask-SocketIO WebSocket + HTTP polling fallback via Web Worker (~60s WebSocket cut by some fronting gateways).
    • Auth: pat_rotator.py — 15-minute PATs rotated every 10 minutes, only while sessions exist; single-user gate makes this safe.
    • Workspace sync: post-commit hook → databricks workspace import-dir; never include .git/.
    • Per-session state lives in process memory (deliberate, no Redis).
    • Extract-vs-document recommendation.
  • README.md — one-line pointer above the existing Architecture ASCII diagram so readers can find the deeper doc.

No code changes.

Test plan

  • Markdown renders cleanly (verified mentally).
  • All cross-links resolve to existing files (docs/plans/2026-02-02-web-terminal-design.md, etc.).

This pull request and its description were written by Claude.

CODA's PTY + SocketIO + xterm + PAT-rotation + sync stack is novel
infrastructure that other Databricks-Apps-hosted-CLI attempts will
re-derive without this doc. Capture it once:

- New docs/architecture/pty-on-apps.md covers each layer (PTY
  allocation, transport, auth, workspace sync, session state), the
  hard constraints (single gunicorn worker, single-user gate,
  no `.git/` in workspace import) with reasons, and an extract-vs-
  document recommendation for if hosted-CLI becomes a recurring pattern.
- README "Architecture" section gets a one-line pointer at the
  reference doc above the existing ASCII diagram.

This PR was prepared by Claude.
@jamesbroadhead jamesbroadhead force-pushed the jb/pty-on-apps-reference-doc branch from 9a11e0b to 13e55de Compare May 28, 2026 09:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant