molecule-ai/molecule-core
51
0
Fork 2
Code Issues 165 Pull Requests 155 Actions 10 Packages Projects Releases Wiki Activity

arch/RFC: workspace-placement (org-per-EC2 architecture) — formalize the implicit design #1793

New Issue
Closed
opened 2026-05-24 09:13:21 +00:00 by hongming · 0 comments
hongming commented 2026-05-24 09:13:21 +00:00
Owner
Copy Link
Copy Source

Summary

Formalize the workspace-placement architecture as a written RFC. The pattern is implicitly already in place: each org/tenant = one EC2, fully isolated, with its own DB and memory plugin. Memory and other state lives ON the tenant (not in the platform), with SSOT and tenant isolation guaranteed by the org-per-EC2 boundary.

This was the design implicit in the 2026-05-24 memory-system migration: the v2 plugin runs as a sidecar on each tenant's EC2, sharing the tenant's Postgres, isolated by EC2 boundary not by application-level multi-tenancy.

Why write it down

  • Future architectural decisions (multi-region, dedicated-tier customers, BYO-compute, etc.) need to reference this pattern.
  • Onboarding new engineers: the mental model "platform is billing/infra-only; tenants are fully functional and self-hosted-shaped" needs an authoritative doc.
  • Implicit-design drift is a real failure mode (e.g., someone could try to centralize memory at the platform layer, breaking SSOT and isolation).

Scope of the RFC

  1. Architecture diagram — platform vs tenant boundary, what crosses (provisioning + billing + tunnel auth) vs what stays (DB, memory, workspace files, agent state).
  2. SSOT rationale — why each tenant owns its own state rather than platform aggregating. Cite this session's "no v1 fallback, v2 plugin is SSOT on the tenant" decision.
  3. OSS-deployment shape — molecule-core is OSS; anyone can deploy a tenant. Their tenant connects to the platform for billing+provisioning but otherwise runs identically to our hosted tenants. Document the workspace's inject org credentials + URL pattern that lets it reach its tenant server.
  4. Scaling envelope — what's the org count this design supports? When does a customer need a dedicated-tier (region-pinned, larger EC2, etc.) vs the default shared shape?
  5. Migration path — for any legacy code that still treats platform as the data-owner, document the deprecation plan.

Location

docs/architecture/workspace-placement.md or internal/runbooks/workspace-placement-rfc.md — wherever architecture decisions live.

Triggers

  • Multi-region or BYO-compute customer ask → RFC must be done first
  • Onboarding a new platform engineer
  • Anyone proposing a platform-side state store that competes with tenant-side state

Acceptance

  • RFC document committed under docs/architecture/ or internal/runbooks/
  • Cross-linked from docs/architecture/molecule-technical-doc.md and from this session's memory.md updates
  • Reviewed by Cui (CEO) — this is a product decision as much as an engineering one
  • Saved as a memory pointer (reference_workspace_placement_rfc) for future agents

Discovered during

Multi-PR memory-system migration 2026-05-24. The architecture was the implicit basis for every design decision in the migration; needs to be made explicit.

## Summary Formalize the workspace-placement architecture as a written RFC. The pattern is implicitly already in place: each org/tenant = one EC2, fully isolated, with its own DB and memory plugin. Memory and other state lives ON the tenant (not in the platform), with SSOT and tenant isolation guaranteed by the org-per-EC2 boundary. This was the design implicit in the 2026-05-24 memory-system migration: the v2 plugin runs as a sidecar on each tenant's EC2, sharing the tenant's Postgres, isolated by EC2 boundary not by application-level multi-tenancy. ## Why write it down - Future architectural decisions (multi-region, dedicated-tier customers, BYO-compute, etc.) need to reference this pattern. - Onboarding new engineers: the mental model "platform is billing/infra-only; tenants are fully functional and self-hosted-shaped" needs an authoritative doc. - Implicit-design drift is a real failure mode (e.g., someone could try to centralize memory at the platform layer, breaking SSOT and isolation). ## Scope of the RFC 1. **Architecture diagram** — platform vs tenant boundary, what crosses (provisioning + billing + tunnel auth) vs what stays (DB, memory, workspace files, agent state). 2. **SSOT rationale** — why each tenant owns its own state rather than platform aggregating. Cite this session's "no v1 fallback, v2 plugin is SSOT on the tenant" decision. 3. **OSS-deployment shape** — molecule-core is OSS; anyone can deploy a tenant. Their tenant connects to the platform for billing+provisioning but otherwise runs identically to our hosted tenants. Document the workspace's `inject org credentials + URL` pattern that lets it reach its tenant server. 4. **Scaling envelope** — what's the org count this design supports? When does a customer need a dedicated-tier (region-pinned, larger EC2, etc.) vs the default shared shape? 5. **Migration path** — for any legacy code that still treats platform as the data-owner, document the deprecation plan. ## Location `docs/architecture/workspace-placement.md` or `internal/runbooks/workspace-placement-rfc.md` — wherever architecture decisions live. ## Triggers - Multi-region or BYO-compute customer ask → RFC must be done first - Onboarding a new platform engineer - Anyone proposing a platform-side state store that competes with tenant-side state ## Acceptance - [ ] RFC document committed under `docs/architecture/` or `internal/runbooks/` - [ ] Cross-linked from `docs/architecture/molecule-technical-doc.md` and from this session's memory.md updates - [ ] Reviewed by Cui (CEO) — this is a product decision as much as an engineering one - [ ] Saved as a memory pointer (`reference_workspace_placement_rfc`) for future agents ## Discovered during Multi-PR memory-system migration 2026-05-24. The architecture was the implicit basis for every design decision in the migration; needs to be made explicit.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
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
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: molecule-ai/molecule-core#1793
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?