flameborn/docs/ARCHITECTURE.md

Architecture

Legal execution model

Cloudflare-hosted web UI cannot safely or directly control a user's privileged local shell.

The supported model is:

Cloudflare or local web app -> browser -> localhost companion runtime -> PTY / shell or Docker sandbox

Components

Web app

• index.html
• script.js
• style.css
• server.mjs

Responsibilities:

• AI chat
• provider routing
• Classroom features
• terminal/sandbox UI
• calling the companion runtime

Companion runtime

• runtime/server.mjs

Responsibilities:

• host command execution
• PTY session management
• Docker session management
• WebSocket streaming
• command safety checks
• local-only trust boundary

Docker sandbox

• runtime/Dockerfile

Responsibilities:

• reproducible execution environment
• isolation
• session workspaces
• bounded CPU/RAM

Runtime endpoints

REST:

• GET /health
• GET /api/runtime/info
• GET /api/terminal/status
• POST /api/terminal/run
• GET /api/sandbox/status
• POST /api/sandbox/run

WebSocket:

• /ws/terminal
• /ws/sandbox-terminal

Design choices

• sudo is never silently executed from the web UI
• Docker sandbox is the preferred publication path
• host execution remains explicit and auditable
• remote access is deny-by-default