docs(arch): #1793 workspace-placement RFC — formalize org-per-EC2 architecture #1819

Merged

hongming merged 1 commits from docs/issue-1793-workspace-placement-rfc into main 2026-05-25 00:09:39 +00:00

Conversation 0 Commits 1 Files Changed 3

+198

hongming commented 2026-05-25 00:04:42 +00:00

Owner

Copy Link

Copy Source

Summary

Closes #1793. Formalizes the org-per-EC2 architecture that has been implicit since the post-2026-05-06 GitHub-suspension rebuild and was the basis for the 2026-05-24 memory v1→v2 migration.

Core contract: every Molecule org runs as a fully isolated tenant on its own EC2, with workspace-server + memory plugin + Postgres + Redis + canvas co-located. The platform (controlplane on Railway) handles provisioning, billing, and DNS — never tenant data.

What the RFC covers

• Boundary diagram — controlplane → tenants, never the data path
• What crosses (provisioning, billing, telemetry) vs what doesn't (memory contents, workspace state, files, sessions)
• SSOT rationale — org isolation is physical (different EC2/DB/network), not application-layer; platform scales independent of tenant data volume; OSS-deployability requires it
• OSS deploy shape — workspaces inject MOLECULE_ORG_ID + MOLECULE_PLATFORM_URL; runtime is agnostic to hosted vs self-hosted platform
• Scaling envelope — 100 → 10K orgs supported by current architecture; 1M-org variant explicitly out of scope
• Decision rules for new features — default: tenant; platform only for billing/anonymized analytics; both rare and tenant-as-SSOT
• Out-of-scope items — multi-region, BYO-compute, OSS billing alternatives (tracked separately)

Cross-links

• docs/architecture/molecule-technical-doc.md §3 now opens with a note linking to the RFC
• docs/architecture/memory.md HMA intro now makes the physical tenant-isolation enforcement explicit, linking to the RFC

Memory pointer

Saved reference_workspace_placement_rfc in the auto-memory index so future Claude sessions encountering architectural design work see the contract before proposing.

Acceptance criteria (from #1793)

• RFC document committed under docs/architecture/
• Cross-linked from docs/architecture/molecule-technical-doc.md and docs/architecture/memory.md
• Reviewed by Cui (CEO) — product framing on OSS-deploy + 1M-org out-of-scope. Mergeable on technical grounds; product review can happen async.
• Saved as memory pointer (reference_workspace_placement_rfc)

SOP Checklist (RFC #351)

1. Comprehensive testing performed

N/A — pure architecture documentation. Diagram + prose verified for internal consistency.

2. Local-postgres E2E run

N/A.

3. Staging-smoke verified or pending

N/A.

4. Root-cause not symptom

The root cause of architectural drift is undocumented decisions becoming implicit. This document removes that surface — anyone proposing a platform-side aggregation of functional state can be pointed at this RFC during review.

5. Five-Axis review walked

Walked solo. Product framing merits Cui's sign-off post-merge (added as acceptance criterion).

6. No backwards-compat shim / dead code added

Pure addition: +198 LOC across 1 new doc + 2 small cross-link edits.

7. Memory/saved-feedback consulted

• reference_post_suspension_pipeline — context for why per-tenant SSOT became the post-suspension architecture
• feedback_no_single_source_of_truth — this RFC encodes the rule at the architecture level

🤖 Generated with Claude Code

## Summary Closes #1793. Formalizes the org-per-EC2 architecture that has been implicit since the post-2026-05-06 GitHub-suspension rebuild and was the basis for the 2026-05-24 memory v1→v2 migration. **Core contract:** every Molecule org runs as a fully isolated tenant on its own EC2, with workspace-server + memory plugin + Postgres + Redis + canvas co-located. The platform (controlplane on Railway) handles provisioning, billing, and DNS — never tenant data. ## What the RFC covers - **Boundary diagram** — controlplane → tenants, never the data path - **What crosses** (provisioning, billing, telemetry) vs what doesn't (memory contents, workspace state, files, sessions) - **SSOT rationale** — org isolation is physical (different EC2/DB/network), not application-layer; platform scales independent of tenant data volume; OSS-deployability requires it - **OSS deploy shape** — workspaces inject `MOLECULE_ORG_ID` + `MOLECULE_PLATFORM_URL`; runtime is agnostic to hosted vs self-hosted platform - **Scaling envelope** — 100 → 10K orgs supported by current architecture; 1M-org variant explicitly out of scope - **Decision rules for new features** — default: tenant; platform only for billing/anonymized analytics; both rare and tenant-as-SSOT - **Out-of-scope items** — multi-region, BYO-compute, OSS billing alternatives (tracked separately) ## Cross-links - `docs/architecture/molecule-technical-doc.md` §3 now opens with a note linking to the RFC - `docs/architecture/memory.md` HMA intro now makes the physical tenant-isolation enforcement explicit, linking to the RFC ## Memory pointer Saved `reference_workspace_placement_rfc` in the auto-memory index so future Claude sessions encountering architectural design work see the contract before proposing. ## Acceptance criteria (from #1793) - [x] RFC document committed under `docs/architecture/` - [x] Cross-linked from `docs/architecture/molecule-technical-doc.md` and `docs/architecture/memory.md` - [ ] **Reviewed by Cui (CEO)** — product framing on OSS-deploy + 1M-org out-of-scope. Mergeable on technical grounds; product review can happen async. - [x] Saved as memory pointer (`reference_workspace_placement_rfc`) ## SOP Checklist (RFC #351) ### 1. Comprehensive testing performed N/A — pure architecture documentation. Diagram + prose verified for internal consistency. ### 2. Local-postgres E2E run N/A. ### 3. Staging-smoke verified or pending N/A. ### 4. Root-cause not symptom The root cause of architectural drift is undocumented decisions becoming implicit. This document removes that surface — anyone proposing a platform-side aggregation of functional state can be pointed at this RFC during review. ### 5. Five-Axis review walked Walked solo. Product framing merits Cui's sign-off post-merge (added as acceptance criterion). ### 6. No backwards-compat shim / dead code added Pure addition: +198 LOC across 1 new doc + 2 small cross-link edits. ### 7. Memory/saved-feedback consulted - `reference_post_suspension_pipeline` — context for why per-tenant SSOT became the post-suspension architecture - `feedback_no_single_source_of_truth` — this RFC encodes the rule at the architecture level 🤖 Generated with [Claude Code](https://claude.com/claude-code)

hongming added 1 commit 2026-05-25 00:04:43 +00:00

docs(arch): #1793 workspace-placement RFC — formalize org-per-EC2 architecture ... b583347d1e

Writes down the architecture decision that has been implicit since the
post-2026-05-06 GitHub-suspension rebuild: every Molecule org runs as
a fully isolated tenant on its own EC2, with workspace-server +
memory plugin + Postgres + Redis + canvas co-located on that
instance. The platform (controlplane on Railway) handles provisioning,
billing, and DNS — it never holds tenant data.

The RFC was the implicit basis for every design decision in the
2026-05-24 memory v1→v2 migration (#1747 → #1791 → #1792). Formalizing
it now so future architectural choices stay aligned. Closes #1793.

## Changes

1. **docs/architecture/workspace-placement.md** (new) — the RFC itself.
   Covers the platform/tenant boundary, what crosses it, SSOT
   rationale, OSS-deployment shape, scaling envelope, decision rules
   for new features, migration path (currently no backlog), and
   explicit out-of-scope items (multi-region, BYO-compute, OSS billing).

2. **docs/architecture/molecule-technical-doc.md** — added a one-line
   note at the top of §3 (System Architecture) linking to the RFC.
   This is the highest-traffic architecture doc; readers landing
   there should see the contract immediately.

3. **docs/architecture/memory.md** — added a paragraph in the HMA
   intro making the tenant-isolation enforcement explicit. HMA's
   organizational-boundary principle is enforced PHYSICALLY (per-EC2
   memory plugin), not at the application layer. Links back to the
   RFC.

## What the RFC does

- Diagrams the boundary (controlplane → tenants, never the data path)
- Lists what crosses (provisioning, billing, telemetry) vs what
  doesn't (memory contents, workspace state, files, sessions)
- Documents SSOT rationale: org isolation, platform scaling
  independent of tenant data volume, OSS-deployability requirements
- Defines OSS deploy shape — workspaces inject MOLECULE_ORG_ID +
  MOLECULE_PLATFORM_URL; runtime is agnostic to whether it's our
  hosted platform or self-hosted
- Sizing envelope (100 → 10K orgs supported by current architecture;
  1M-org variant explicitly out of scope)
- Decision rules for new feature design (default: tenant; platform
  only for billing/anonymized analytics; both rare and tenant-as-SSOT)

## What this RFC does NOT cover (separately tracked)

- Multi-region tenant placement (needs its own RFC)
- BYO-compute / customer-managed VPC
- Workspace runtime selection (docs/architecture/workspace-tiers.md)
- Tenant image upgrades (docs/architecture/tenant-image-upgrades.md)
- OSS billing alternatives

## SOP Checklist (RFC #351)

### 1. Comprehensive testing performed
N/A — pure architecture documentation. Diagram + prose verified for
internal consistency.

### 2. Local-postgres E2E run
N/A.

### 3. Staging-smoke verified or pending
N/A.

### 4. Root-cause not symptom
The root cause of architectural drift is undocumented decisions
becoming implicit. This document removes that surface — anyone
proposing a platform-side aggregation of functional state can be
pointed at this RFC during review.

### 5. Five-Axis review walked
Walked solo. The product framing (especially OSS-deploy shape +
1M-org out-of-scope) merits Cui's sign-off post-merge — added
'Reviewed by Cui' as an acceptance criterion in #1793's body. PR
is mergeable on technical grounds; product review can happen async.

### 6. No backwards-compat shim / dead code added
Pure addition. +218 LOC across 1 new doc + 2 small cross-link
edits in existing docs.

### 7. Memory/saved-feedback consulted
- 'reference_post_suspension_pipeline' — context for why per-tenant
  SSOT became the architecture post-suspension
- 'feedback_no_single_source_of_truth' — this RFC encodes the rule
  at the architecture level
- Saved new memory pointer 'reference_workspace_placement_rfc' linking
  to this doc so future Claude sessions reach it before design work

Closes #1793.

devops-engineer approved these changes 2026-05-25 00:04:45 +00:00

devops-engineer left a comment

Member

Copy Link

Copy Source

Approving PR #1819: docs-only RFC formalizing the org-per-EC2 architecture. Acceptance criteria all met except Cui sign-off (called out, async-mergeable). CTO-bypass 2026-05-24.

Approving PR #1819: docs-only RFC formalizing the org-per-EC2 architecture. Acceptance criteria all met except Cui sign-off (called out, async-mergeable). CTO-bypass 2026-05-24.

core-devops approved these changes 2026-05-25 00:04:46 +00:00

core-devops left a comment

Member

Copy Link

Copy Source

Approving PR #1819: docs-only RFC formalizing the org-per-EC2 architecture. Acceptance criteria all met except Cui sign-off (called out, async-mergeable). CTO-bypass 2026-05-24.

Approving PR #1819: docs-only RFC formalizing the org-per-EC2 architecture. Acceptance criteria all met except Cui sign-off (called out, async-mergeable). CTO-bypass 2026-05-24.

hongming merged commit 6964b26474 into main 2026-05-25 00:09:39 +00:00

hongming referenced this issue from a commit 2026-05-25 00:09:41 +00:00

docs(arch): #1793 workspace-placement RFC — formalize org-per-EC2 architecture (#1819)

Sign in to join this conversation.

Reviewers

No Reviewers

devops-engineer

core-devops

Labels

Clear labels

area/ci

CI/CD pipeline issues

do-not-auto-merge

Opt out of autonomous merge-queue merging

kind/infrastructure

Infrastructure-related issues

merge-queue

Ready for serialized Gitea merge queue

merge-queue-hold

Temporarily hold PR in merge queue

platform/go

Go platform test issues

release-blocker

Blocks the staging→main promotion / a release

release-test

security

test-label-sre

tier:high

High risk per dev-sop §SOP-6 — ceo only, 24h cooldown

tier:low

Low risk per dev-sop §SOP-6 — engineers/managers/ceo can approve

tier:medium

Medium risk per dev-sop §SOP-6 — managers/ceo can approve

triage-test

test

wip

Work in progress — do not auto-merge

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

agent-dev-a agent-dev-b agent-pm agent-researcher agent-reviewer agent-reviewer-1 agent-reviewer-cr2 app-fe (Molecule AI · app-fe) app-lead (Molecule AI · app-lead) app-qa (Molecule AI · app-qa) claude-ceo-assistant claude-ci-reader claude-status-reaper core-be (Molecule AI · core-be) core-devops (Molecule AI · core-devops) core-fe (Molecule AI · core-fe) core-lead (Molecule AI · core-lead) core-offsec (Molecule AI · core-offsec) core-qa (Molecule AI · core-qa) core-security (Molecule AI · core-security) core-uiux (Molecule AI · core-uiux) cp-be (Molecule AI · cp-be) cp-lead (Molecule AI · cp-lead) cp-qa (Molecule AI · cp-qa) cp-security (Molecule AI · cp-security) cui (Zhanlin Cui) dev-lead (Molecule AI · dev-lead) devops-engineer documentation-specialist (Molecule AI · documentation-specialist) fullstack-engineer (Molecule AI · fullstack-engineer) hongming hongming-ceo-delegated hongming-codex-laptop hongming-kimi-laptop hongming-pc2 infra-lead (Molecule AI · infra-lead) infra-runtime-be (Molecule AI · infra-runtime-be) infra-sre (Molecule AI · infra-sre) integration-tester (Molecule AI · integration-tester) mc-drift-bot molecule-code-reviewer plugin-dev (Molecule AI · plugin-dev) pm publish-runtime-bot pypi-publisher (Molecule AI PyPI Publisher (RFC#596)) release-manager (Molecule AI · release-manager) sdk-dev (Molecule AI · sdk-dev) sdk-lead (Molecule AI · sdk-lead) sop-drift-bot sop-tier-bot (SOP Tier-Check Bot) technical-writer (Molecule AI · technical-writer) triage-operator (Molecule AI · triage-operator)

No Assignees

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: molecule-ai/molecule-core#1819