Production architecture with Fargate canary

At a glance

Verified against live prod (chat.think2earn.com), EC2 i-076d244b62ec4d8e8 (think2earn-prod), account 995772916887, region us-east-1, and stack think2earn-harness (handoff 2026-07-08; E2E 33/33, isolation probes 18/18).

Default Production control plane

One long-lived EC2 host still fronts the entire web product. The Fargate plane does not replace the API — it only executes allowlisted agent-mode turns.

flowchart TB
  subgraph users [Users]
    Browser[Browser]
  end

  subgraph edge [Cloudflare]
    CF_DNS[DNS]
    CF_Tunnel[Tunnel to origin]
  end

  subgraph ec2 [Control plane EC2 think2earn-prod]
    Cloudflared[cloudflared]
    NodeApp[Node Express API plus Vite SPA]
    Journal[Turn journal memory plus DDB]
    Router[effectiveHarnessRuntime]
    IAMHost[Think2earnHostRole]
  end

  subgraph agentcore_path [Agent path default]
    Runtime[AgentCore Runtime microVM]
  end

  subgraph fargate_path [Agent path canary]
    Kick[SQS turn-kick]
    Dispatch[dispatch-turn Lambda]
    Task[ECS Fargate worker]
    Vend[vend-credentials Lambda]
    Finalize[finalize-turn Lambda]
  end

  subgraph tools [Shared tool services]
    Converse[Bedrock ConverseStream]
    CI[Code Interpreter]
    BrowserAC[Browser CDP]
    Memory[AgentCore Memory]
    Gateway[Exa Gateway]
  end

  subgraph data [AWS data]
    DDB[(DynamoDB core plus journal plus dispatch)]
    S3[(S3 artifacts and staging)]
  end

  Browser --> CF_DNS --> CF_Tunnel --> Cloudflared --> NodeApp
  NodeApp --> Journal
  NodeApp --> Router
  NodeApp --> DDB
  NodeApp --> S3
  NodeApp --> IAMHost
  IAMHost --> Converse
  IAMHost --> CI
  IAMHost --> BrowserAC
  IAMHost --> Memory
  IAMHost --> Gateway
  Router -->|not allowlisted agent mode| Runtime
  Router -->|allowlisted agent mode| Kick --> Dispatch --> Task
  Task --> Vend
  Task --> Journal
  Task --> S3
  Task --> Converse
  Task -.-> Finalize
      

Request paths that every user hits

Characteristics (still true)

• Single API host — API, SPA, billing, SSE relay, and simple-mode tools share one EC2 process.
• Shared host IAM for AgentCore tools — tenants share Think2earnHostRole; app-layer org/user/conversation isolation.
• E8 detached turns — client disconnect no longer aborts; Stop uses explicit cancel; reattach via journal + /active-turn.
• Env is not the repo .env — systemd loads think2earn-management.env (+ local overrides); deploy rsync excludes env.
• Architecture static site — this page is separate on Cloudflare Pages (architecture.think2earn.com); product SPA is still served from EC2.

Canary Fargate worker plane (live)

Option B from the Jul 2026 architecture decision is partially shipped: AgentCore is no longer the only agent executor. The worker plane runs each allowlisted agent turn in its own throwaway container; isolation is IAM math (vended session policy), not process trust.

Lambdas (one job each)

Worker container

• Image: …/think2earn-harness-node:efea455 (taskdef revision :4)
• Near-zero task role; real data access only after vend
• Claude Agent SDK with bypassPermissions — isolation is the vended IAM scope (probes: 18/18)
• Stages nothing from conversations table: EC2 stages input.json under the user S3 prefix first
• Env contract: IDs and pointers only — no prompt, no AWS keys in RunTask overrides
• Journal events as primary telemetry (successful workers often log nothing to CloudWatch)

Temporary Canary user allowlist

Routing is decided in the EC2 app by effectiveHarnessRuntime(userId) (src/config.ts). Global flag stays agentcore; only listed user IDs take Fargate.

flowchart TD
  POST["POST /chats/:id/messages agent mode"]
  Check{"effectiveHarnessRuntime userId"}
  Global{"HARNESS_RUNTIME = fargate?"}
  Allow{"userId in FARGATE_USER_ALLOWLIST?"}
  AC["AgentCore SSE path 200"]
  FG["startTurn: stage S3 + journal META + dispatch QUEUED + SQS kick"]
  R202["202 mode fargate-async"]
  Poll["Client polls GET .../turns/:requestId/events"]

  POST --> Check
  Check --> Global
  Global -->|yes| FG
  Global -->|no| Allow
  Allow -->|yes| FG
  Allow -->|no| AC
  FG --> R202 --> Poll
      

How to change / roll back the canary

Canary path Fargate turn lifecycle

sequenceDiagram
  participant C as Client
  participant E as EC2 app
  participant S3 as S3 staging
  participant J as turn_journal
  participant D as turn_dispatch
  participant Q as SQS kick
  participant L as dispatch-turn
  participant T as Fargate worker
  participant V as vend-credentials
  participant F as finalize-turn

  C->>E: POST messages agent mode allowlisted
  E->>S3: put input.json under users/userId
  E->>J: META runtime fargate
  E->>D: row QUEUED
  E->>Q: SendMessage kick
  E-->>C: 202 requestId mode fargate-async
  C->>J: poll events
  Q->>L: kick
  L->>D: claim QUEUED to DISPATCHING
  L->>T: RunTask
  L->>D: RUNNING
  T->>V: vend scoped creds
  V-->>T: temporary credentials
  T->>J: stream events artifacts done
  T->>S3: artifact sweep
  Note over T,F: task STOP EventBridge
  F->>D: DONE or FAILED or CANCELLED
  F->>E: settlement message plus dock rows
      

Cancel semantics

• POST …/turns/:requestId/cancel
• QUEUED: synthetic done; no RunTask
• DISPATCHING / RUNNING: set journal META.cancelRequested; worker polls ~5 s, aborts, truncated sweep
• Client poll terminal for cancelled: 409 {"error":"truncated"} (not a hang)
• billable=false on truncated done events

Capacity & safety

• Concurrency derived from dispatch status (no leaky counters): 3 concurrent / user, 60 global
• 4th concurrent turn stays QUEUED with queuePosition
• Sweeper reconciles stuck rows; DLQ alarms on think2earn-turn-kick-dlq
• Budget alarm: think2earn-harness-monthly $200/mo, >80% ACTUAL → operator email
• Kill switch: SSM /think2earn/dispatch-enabled

Compute paths compared

Data & state

Live stack inventory

Repo map

Next Roadmap from here

1. Canary week (now) — real use on allowlisted Carol identities; measure kick→first-event latency, vend errors, DLQ, cost delta.
2. W2-D image slimming + SOCI — baseline ~34–37 s to first journal event / ~46–51 s done (haiku); target ≤~30 s first event.
3. Linger-window decision — whether follow-up turns reuse a warm task vs pay cold start every time.
4. §14 step 7 global cutover — THINK2EARN_HARNESS_RUNTIME=fargate; allowlist moot; then decommission AgentCore chat path.
5. Later control-plane migration — SPA on CDN; API off EC2; Cloudflare Tunnel only until that split lands.

What changed vs the old architecture page (2026-06-30)

The previous page claimed a pure “current EC2 / target serverless AgentCore Runtime” split and said the turn journal was only in-memory. Several of those claims are now wrong or incomplete after the Fargate worker plane landed.

What stayed the same

• Public product URL and Cloudflare Tunnel → EC2 edge path
• Default chatMode: simple + Bedrock ConverseStream on the host
• Cognito / native auth / app JWT and Stripe credit billing
• Shared AgentCore tool resources (Browser, Code Interpreter, Memory, Exa Gateway) for simple mode
• S3 artifact bucket + conversation artifact dock model
• Account 995772916887, region us-east-1, prod instance i-076d244b62ec4d8e8

Still out of scope for this phase

• Per-user dedicated EC2 + DCV desktop as the agent runtime
• Standalone CLI binary
• Full integrations OAuth marketplace
• Replacing Exa Gateway with a different search provider (unless product decides later)
• Global Fargate cutover before canary exit criteria