edward-end-to-end-flow

Edward — End-to-End Execution Flow, Step by Step

Repo: github.com/pragnya-works/Edward · every claim below is read from the code (file paths in each section). What this is: the complete path from "user sends a message" to "preview URL streams back", component by component, in the order the code actually runs.

0. The map (who does what)

1. The request lands: transport hardening + Zod

1. App construction — createHttpApp() sets trust proxy, then Helmet: HSTS (1 year, includeSubDomains, preload), CSP (defaultSrc 'self', scripts 'self', images data: + https), frameguard: deny, noSniff.
2. Prod only — createForceHttpsMiddleware() reads x-forwarded-proto; anything not https is 308-redirected to https://host + originalUrl.

2. Admission control, step by step

Two layers, in this order: rate limit (Redis, cheap, per-scope) then admission (Postgres, authoritative, concurrency).

2a. Rate limits (middleware/rateLimit.ts)

1. Every limiter is built by createRateLimiterForScope(scope), which looks the policy up in RATE_LIMIT_POLICY_BY_SCOPE (@edward/shared/constants). If the policy is missing it throws at import time ("Rebuild @edward/shared…") — a guard against dist/source drift.
2. Store is rate-limit-redis on the same Redis connection, keyed rl:<policyPrefix>:, keyed by userId when authenticated (fallback: ipKeyGenerator).
3. Scopes in play: chat burst (10/min), chat daily (10 / 24h), quota read (30/min), image upload (6/min), prompt enhance (3/min), API-key (10/15min), GitHub (20/min, 400/day).
4. On breach: set RateLimit-Scope, log security telemetry, return 429 with the policy's message.
5. The daily chat limiter is special — it is applied after the burst limiter and is a success-only quota: a separate daily-success counter (chatDailySuccess.service.ts) decides what actually burns the allowance, and are hand-set from a snapshot.

2b. Window check (getRunAdmissionWindow)

1. count() all rows in run whose status is in ACTIVE_RUN_STATUSES (queued, running) → activeRunDepth.
2. userRunLimit = min(MAX_ACTIVE_RUNS_PER_USER=2, AGENT_RUN_WORKER_CONCURRENCY=max(configured,2)) — the per-user cap can never exceed the worker's own concurrency.
3. overloaded = activeRunDepth >= MAX_AGENT_QUEUE_DEPTH (200). If overloaded → the request is rejected here with a stream 429 "under high load" and no run row is created.

2c. The admitted run (createRunWithUserLimit, packages/auth/lib/run.ts)

This is the step-by-step core you asked about:

1. Open one Postgres transaction.
2. Lock globally: pg_advisory_xact_lock(hashtext('run_admission_global')) — a single writer for the global count.
3. Lock per user: pg_advisory_xact_lock(hashtext(userId)) — this is why two messages fired at the same instant by the same user can't both pass. (Transaction-scoped advisory locks release automatically on commit/rollback, so there is no lock leak if the request dies mid-way.)
4. Count active runs globally; if >= maxActiveRunsGlobal (200) → return {run: null, rejectedBy: "global_limit"}.
5. Count active runs for this user; if >= maxActiveRunsPerUser (2) → "user_limit".
6. Count active runs for this chat; if >= maxActiveRunsPerChat (1) → "chat_limit".

States a run walks through (RunState): INIT → LLM_STREAM → TOOL_EXEC → APPLY → NEXT_TURN → COMPLETE | FAILED | CANCELLED.

3. The queue, step by step (services/queue/*)

1. Two BullMQ queues on Redis (lib/queue.binding.ts): chat-processing-queue (BUILD + BACKUP) and agent-run-queue (AGENT_RUN).
2. Every payload is Zod-validated before it is added (BuildJobPayloadSchema.parse / AgentRunJobPayloadSchema.parse) — an invalid job can't enter the queue even from internal code.
3. Deterministic job ids = natural dedupe. Agent run: agent-run-<runId>. Build: build-<sandboxId>-<buildId|chatId:messageId> (identifier sanitized to [a-zA-Z0-9:_-]). Before adding, the code calls getJob(jobId); if it exists, it returns the job id instead of duplicating work.

4. The worker, step by step (apps/api/queue.worker.ts)

1. Boot: dotenv, then new Worker(BUILD_QUEUE_NAME, handler, { connection, concurrency: BUILD_WORKER_CONCURRENCY }) and the same for AGENT_RUN_QUEUE_NAME with AGENT_RUN_WORKER_CONCURRENCY.
2. Agent-run dispatch: the handler parses with JobPayloadSchema.parse(job.data); anything that is not AGENT_RUN on that queue is logged and thrown (no silent mis-execution).
3. Build dispatch: BuildQueueJobPayloadSchema.safeParse then a switch on BUILD / BACKUP; unknown types throw.

4a. Build job handler, step by step (workerJobHandlers.service.ts)

1. Resolve (or create) the build row; if it's already terminal (success/failed) → just re-publish its status and exit (idempotent duplicate handling).
2. Claim via conditional UPDATE: UPDATE build SET status='building' WHERE id=? AND status='queued' — only the winner gets a row back. Losers either see it terminal or "already claimed" and exit. This is the concurrency guard.
3. Publish building to edward:build-status:<chatId> (with retry).
4. Run buildAndUploadUnified(sandboxId) under withTimeout(WORKER_BUILD_JOB_TIMEOUT_MS).
5. On success: updateBuild(success, previewUrl, buildDuration), publish , then enqueue a job (non-fatal if that fails).

5. The agent-run worker: orchestration, step by step (services/runs/agent-run-worker/processor.ts)

1. getRunById(runId); if missing → throw; if already terminal → return (no double terminal transitions).
2. Terminal-event guard: if a session_complete meta event already exists for the run, map its termination reason to a status and finish without re-running the session.
3. Create the worker's AbortController and subscribe to the run's cancel channel edward:run-cancel:<runId>. A message on that channel aborts the stream — this is how the UI's Stop reaches a live worker in another process.
4. Start a status watchdog every RUN_TERMINAL_STATUS_POLL_INTERVAL_MS (2 s); if the run row became terminal elsewhere (another worker, a reaper), abort locally.
5. Parse run.metadata (parseAgentRunMetadata). Failure → mark run FAILED with the parse error.
6. Load the user's BYOK key and decrypt it (AES-256-GCM). Missing key / decrypt failure / unknown provider → FAILED with a user-facing message.

5a. What happens inside the session (services/chat/session/*)

1. Framework resolution — frameworkResolution.ts uses the workflow's intent: nextjs / vite-react / vanilla, or recovers the framework from an existing sandbox/Redis.
2. Prompt assembly — composePrompt() with a profile (DEFAULT/STRICT), modular system-prompt sections plus compacted skill packs.
3. Token budget — computeTokenUsage() per provider (tiktoken for OpenAI, provider counters for Gemini/Anthropic, reserved output tokens, vision overhead).
4. Turn loop — agentLoop.runner.ts / : max turns, max tool calls per turn (12) and per run (24) from ; each turn streams from with up to 2 stream attempts per turn.

6. The custom streaming parser, step by step (lib/llm/parser.ts, parser.shared.ts, parser.content.ts, parser.textSandbox.ts)

The model is instructed to emit tag-delimited blocks. The parser is a state machine over a rolling buffer, not a regex pass:

1. State starts TEXT. Buffer is capped at MAX_BUFFER_SIZE (10 KB) — on overflow the oldest bytes are dropped.
2. Each process(chunk) appends the chunk and then loops handleState() until the buffer stops shrinking or MAX_ITERATIONS (1000) is hit; hitting the cap emits a fatal parser_iterations_exceeded ERROR event and resets to TEXT (infinite-loop guard).
3. States: TEXT → THINKING → SANDBOX → FILE → INSTALL (enum StreamState).
4. Tags come from ASSISTANT_STREAM_TAGS (): thinking start/end, start/end, file start/end (with dynamic path), install start/end, command, web search, url scrape, response, done.

7. Handling each event: writes, installs, commands (services/chat/session/events/*)

1. SANDBOX_START → if the workflow has no sandbox, ensureSandbox() provisions/reuses one and marks sandboxTagDetected (nothing else may touch the sandbox before this tag).
2. FILE_START → prepareSandboxFile(): acquire the flush lock, delete any Redis buffer for that path, mkdir -p the parent inside the container, truncate -s 0 the target. The in-memory generatedFiles map gets the path.
3. FILE_CONTENT → handleFileContent() strips a leading ``` fence on the first chunk, then (section 8). Content is also appended to in memory for post-gen validation.

8. Buffering the generated code and writing it into the container, step by step

This is the part most people miss: the model's bytes never go straight into Docker. They are debounced in Redis and flushed in batches.

1. Buffer keys (sandbox/write/shared.ts): edward:buffer:<sandboxId>:<path> (the content, appended) and edward:buffer:files:<sandboxId> (a set of dirty paths). TTL on both = SANDBOX_TTL (15 min).
2. writeSandboxFile()
   1. Resolve sandbox state from Redis; normalize the path (reject absolute, .., empty) — a second path jail independent of the command one.
   2. isProtectedFile(path, framework) — template files (package.json, tsconfig.json, , , , , …) are , so the model can't break the scaffold.

9. The Docker container: invocation, template auto-selection, isolation, step by step

9a. When it is invoked

The sandbox is provisioned lazily, on the first SANDBOX_START/file event of a run (ensureSandbox) or explicitly by the workflow's install/build phases. Nothing is pre-created per message.

9b. Template / image auto-selection (templates/template.registry.ts, framework.contracts.ts)

1. The framework comes from the intent analyzer (an LLM classification, section 5a) or from an explicit preference detected in the user's words (frameworkPreference.ts), and is cached in Redis per chat (edward:chat:framework:<chatId>, 7-day TTL) so follow-ups reuse it.
2. normalizeFramework() maps aliases (next, next.js → nextjs; react, vite → vite-react; vanilla).

9c. Provisioning, step by step (lifecycle/provisioning.ts)

1. waitForProvisioning(chatId) polls for an existing active sandbox (or a live edward:locking:provision:<chatId> lock) up to PROVISIONING_TIMEOUT_MS (30 s).
2. acquireDistributedLock('edward:locking:provision:<chatId>', 60 s) — SET NX PX + Lua CAS release, so exactly one provisioning runs per chat across all API/worker processes. Failing the lock → jittered retry (200–500 ms), up to 10 attempts, then "lock acquisition timeout".
3. Double-check getActiveSandbox(chatId) under the lock (someone may have finished while we waited) and return it if present.
4. nanoid(12) sandbox id; lifecycle state → PROVISIONING (Redis lifecycle record).
5. createContainer(userId, chatId, sandboxId, image):

9d. The network window (how packages install in an isolated container)

1. The container is created network-less and verified so.
2. INSTALL_PACKAGES (steps/executeInstallPhase.ts) calls connectToNetwork(containerId), then mergeAndInstallDependencies(...) (pnpm), then always calls disconnectContainerFromNetwork(...) — success or failure, and even if the install threw (the error is captured first, disconnect runs after).
3. buildAndUploadUnified does the same: it connects at the start, may install pnpm globally / run pnpm install --frozen-lockfile=false if node_modules is missing, and disconnects on return path including the catch block.

10. Build: validation, unified build, upload, step by step

1. Package resolution first (RESOLVE_PACKAGES, dependency.resolver.ts + registry/package.registry.ts): normalize specs, block a blocked-package list, validate each package against the npm registry, cache results in Redis, and mark each valid/invalid. The valid set becomes resolvedPackages before anything is installed.
2. Install (9d) with retries: INSTALL_PACKAGES = 3 retries, 120 s timeout (workflow/config.ts).
3. processBuildPipeline (in-session, right after the loop):

11. "If an error occurs during build, how does it get fixed" — the five fix layers, step by step

The repair strategy is layered, cheapest first. Nothing here is "hope the model notices".

1. Deterministic in-place autofixes (no model involved) — postgenAutofix.ts:
   • rewrites broken zustand default imports into { create as X } form,
   • forces <link rel="canonical"> hrefs in index.html to absolute https URLs (a href="/" makes Vite's build-html read a directory and crash),
   • the sanitize step (section 7.4) strips CDATA/fences/HTML entities from every written file.
2. Static post-gen validators — planning/validators/postgenValidator.*: framework, imports, logic, SEO and constants. Each violation carries a severity; recoverable ones are streamed to the user as [Validation] …, and ones are collected into a blocking report.

12. Saving: Postgres (truth) vs Redis/Upstash (live), step by step

12a. Postgres — durable truth

1. run — every run: id, chatId, userId, userMessageId, assistantMessageId, status, state, currentTurn, nextEventSeq, loopStopReason, , , , timestamps. State is updated at each phase (, , , , …) and on checkpoint.

12b. Redis (Upstash-compatible, single shared instance) — live state

The API and worker talk to one Redis through lib/redis.ts (ioredis, REDIS_URL host+port parsed in app.config.ts, maxRetriesPerRequest: null). Every key family:

12c. S3 + the backup path

Build output is uploaded per user/chat prefix (buildS3Key(userId, chatId, 'preview/…')), and the sandbox source is archived (source_backup.tar.gz, gz + tar) on a BACKUP job and on cleanup, with a Redis flag and an S3 HeadObject check so restore can find it later.

13. Streaming back to the user, step by step

Two paths run in parallel on purpose: Postgres for correctness, Redis for liveness.

1. Producer side (worker): for every parsed event, persistRunEvent(runId, event, publisher) does appendRunEvent (Postgres, gets seq) and then publisher.publish("edward:run-events:<runId>", {id, runId, seq, eventType, event}) (Redis). The DB is the truth; Redis is the live fan-out. If the subscriber is down, nothing is lost — the DB replay still has it.
2. Consumer side — the same request that POSTed the message stays open and unifiedSendMessage ends by calling streamRunEventsFromPersistence({req, res, runId}). So /chat/message itself is the SSE stream; the client never has to poll.
   • Headers: Content-Type: text/event-stream, , .

14. Preview hosting: CloudFront + Cloudflare Worker + KV + Durable Object, step by step

Two deployment modes (EDWARD_DEPLOYMENT_TYPE, auto-resolved to subdomain when complete Cloudflare config exists, else path).

14a. What the API does after a successful upload

1. Files land in S3 under <sanitizedUserId>/<sanitizedChatId>/preview/… with sanitized key components and content types mapped by extension.
2. CloudFront cache invalidation — invalidatePreviewCache(userId, chatId) creates an invalidation for /<userId>/<chatId>/preview/* via @aws-sdk/client-cloudfront (non-fatal on failure).
3. Subdomain assignment (previewRouting/subdomain.ts): if the chat has no customSubdomain yet, one is generated deterministically from sha256(userId:chatId) → a unique-names-generator adjective-animal name plus a 5-char base36 suffix (attempt 2+ mixes in the attempt number). It's claimed with a conditional and retried up to 5 times on a unique-constraint collision. User-chosen subdomains are validated first: length 3–63, , and a reserved-word list.

14b. What the Cloudflare Worker does on every request (scripts/worker.js, wrangler.toml)

Config: worker edwardd-router, route *.edwardd.app/*, KV binding SUBDOMAIN_MAPPINGS, Durable Object binding RATE_LIMITER (migration v1, new_sqlite_classes).

1. Read env.CLOUDFRONT_URL; if unset → 500 "Worker misconfigured".
2. Split the hostname; if there is no subdomain or it's in the RESERVED set (www, api, admin, app, mail, dashboard, ftp, dev, smtp, staging, preview, static, assets, cdn, media, files, storage) → plain 200 "Welcome to Edwardd". This is what keeps the apex/marketing and reserved hosts out of the preview path.
3. Only GET/HEAD are allowed → anything else is 405.
4. Rate limit per subdomain via the Durable Object: idFromName(subdomain) → POST /check. The DO keeps a per-minute window (Math.floor(Date.now()/60000)) and a count in its own storage (loaded in blockConcurrencyWhile), with a cap; over the cap → 429 + seconds to the next minute boundary. If the DO binding is missing or errors, it fails open.

End-to-end subdomain flow: user prompt → build → S3 preview/ → CloudFront invalidation → KV subdomain → userId/chatId → a request to https://<subdomain>.edwardd.app/<route> hits the Worker → DO rate check → KV lookup → CloudFront fetch of <prefix>/preview/index.html or the asset → hardened response with the iframe CSP.

15. One-paragraph recap of the whole chain

POST /chat/message → Helmet/CORS/1 MB → Zod → Redis rate limits → getRunAdmissionWindow → createRunWithUserLimit under two Postgres advisory locks (global, user) and three caps (200 global / 2 per user / 1 per chat) → run row queued/INIT → BullMQ agent-run-queue (job id agent-run-<runId>) → worker picks it up, subscribes to the cancel channel, decrypts the BYOK key, reconstructs history → runStreamSession decides the framework, assembles the prompt, computes the token budget and streams model output through the custom tag parser → typed events drive sandbox provisioning (a locked, network-isolated, non-root node:22-slim container from the framework template), file writes (Redis-buffered, debounce → cat >> into the container), sanitize, installs (only inside a briefly opened network window) and commands (allow-list + path jail) → autofixes, validates and enqueues a build → worker claims the build row with a conditional UPDATE, runs syntax/types/build validation in the container, fixes via strict re-generation / RECOVER, diagnoses failures into a structured report → artifacts upload to S3, CloudFront invalidates, the subdomain is claimed in Postgres and mapped in Cloudflare KV → every event is written to Postgres ( with a monotonic seq) published to Redis → the still-open SSE stream replays Postgres from while live Redis events are buffered and merged by seq, with backpressure and heartbeats → the browser renders the stream and can resume mid-build → the Cloudflare Worker resolves through the Durable-Object limiter and KV to CloudFront, enforcing path safety, caching and the iframe CSP.

16. Gaps / things worth knowing

• Path vs subdomain preview are both live paths in the code; which one you get depends on complete Cloudflare config (EDWARD_DEPLOYMENT_TYPE wins, otherwise auto).
• The DEPLOY phase is a formality in stepRunner.ts — it just checks that state.context.previewUrl exists. The real publishing happens in the build orchestrator's upload/registration step.
• Preview URLs are only registered for chats with userId and chatId on the sandbox; otherwise upload/cleanup is skipped with a warning.
• Several non-fatal steps are deliberately swallowed (CloudFront invalidation, SPA fallback upload, stale-preview cleanup, post-build backup enqueue) — the build still succeeds.
• Redis is the single point of coordination: locks, buffers, rate limits, pub/sub and BullMQ all share it. If it's unavailable, admission still works (Postgres) but queueing, streaming fan-out and file flushing do not.
• The container pins User: "node" on create on every exec, and fails closed — a container that can't be isolated is destroyed rather than used.