</>Code Editor / Architecture

System overview · proposed public release

Write in the browser.
Run in isolation.

An exercise-based Python and TypeScript editor with automatic saving, resumable agent conversations, and a TypeScript worker that runs code in isolated sandboxes.

Planned architecture React + Monaco Render API + TypeScript worker Supabase durable queues Vercel AI SDK selected OpenRouter candidate · Modal selected

Architecture diagram

Solid paths show requests, jobs, and results. Dashed paths show repository deployment.

Proposed exercise editor, agent, queue, worker, and sandbox architecture A private GitHub repository deploys a static site, a public Fastify API, and a separate TypeScript background worker. The browser signs in through Supabase Auth and sends exercise edits, manual run requests, and agent messages to the API. The API saves job records and enqueues their IDs in durable Supabase Postgres queues. One worker has independent agent-turn and code-run consumers. The agent consumer uses Vercel AI SDK Core, calls the configured model gateway, and can enqueue a code run; OpenRouter remains the gateway candidate. The run consumer creates a fresh Modal Sandbox for user Python or TypeScript. The worker stores bounded results in Postgres; the API streams authorized results to the browser. Provider credentials stay in the worker, outside the public API and sandboxes. DELIVERY AND INFERENCE APPLICATION DURABLE STATE AND JOBS UNTRUSTED CODE BOUNDARY HTTPS SSE enqueue status jobs results run output PUBLIC ASSETS Render Static Site Vite build · HTML, CSS, JS SOURCE + DELIVERY Private GitHub repo Monorepo · CI checks · deploys MODEL PROVIDER CANDIDATE OpenRouter Configurable model inference USER DEVICE Browser editor React + Monaco Exercise + language switch main.py + main.ts Autosave · Run · conversation Sign in before execution PUBLIC BACKEND Fastify API Render web service · TypeScript Auth, ownership, quotas Exercise files + revisions Persist + enqueue job IDs SSE output + cancellation PRIVATE BACKEND TypeScript worker Render background service Agent turns AI SDK Core Code runs Modal SDK Independent concurrency STATE + DURABLE QUEUES Supabase Postgres Auth · exercises · revisions Conversations · turns · runs agent_turns · code_runs Status · bounded output UNTRUSTED CODE Modal Sandboxes Fresh environment per run Python pinned runtime TypeScript compile → Node No network/secrets · limits
Request or service access Results and output Deployment or policy
Runtime path: browser → API → durable queues → TypeScript worker with Vercel AI SDK Core → configured model gateway or Modal Sandbox. OpenRouter remains the gateway candidate. Results return through Postgres and the API.

Components

Each part has one clear responsibility. Hosting choices are the current recommendation, not deployed infrastructure.

01 / WEB APPPlanned

Editor and output

React, Monaco, and Supabase Auth provide sign-in, an exercise draft for each language, automatic saving, Run output, and exercise conversations. Render Static Site is the proposed host for the Vite build.

02 / PUBLIC APIScaffolded

Fastify boundary

The TypeScript API authenticates users, checks ownership and quotas, saves exercise revisions and immutable job records, enqueues IDs, and streams authorized results. It holds neither model nor sandbox credentials.

03 / WORKERPlanned

Agent and run consumers

One TypeScript Render background worker initially consumes two queues with independent concurrency. Agent turns use Vercel AI SDK Core to call the configured model provider and checkpoint every step in Postgres; code runs create Modal Sandboxes. Split the consumers into services if load requires it.

04 / EXECUTIONSelected

Isolated code

Modal Sandboxes execute a recorded Python or TypeScript snapshot in a fresh environment with pinned runtimes, blocked networking, no application secrets, and time, compute, and output limits.

05 / STATESelected

Postgres and queues

Supabase Auth and Postgres store users, exercises, revisions, conversations, turns, run records, and bounded output. Two durable queues carry job IDs. Records and queue messages are created together.

06 / DELIVERYPlanned

One repository, separate deploys

The private GitHub monorepo holds the web app, API, worker, and shared contracts. The API and worker are separate processes. See the living cost model for the two-service baseline.

How it works

The backend owns server work; the browser owns the editing experience.

01 / AUTOSAVE

Persist edits

The first edit sends the active main file to the exercise API immediately. Further edits are combined while the request runs and for about one second afterward; the latest version is then saved. The server confirms each saved revision.

02 / ENQUEUE

Record the work

The API authorizes a manual run or agent turn, saves its state, and enqueues its ID in Postgres. An agent can enqueue a code run through the same path as the Run button.

03 / WORK

Execute and stream

The worker uses Vercel AI SDK Core to call the configured model gateway or runs a Modal Sandbox, persists each model/tool checkpoint plus bounded output and status, then acknowledges the job. The API streams authorized results; the worker removes each finished sandbox.