forked from molecule-ai/molecule-core
24fec62d7f
Forked clean from public hackathon repo (Starfire-AgentTeam, BSL 1.1) with full rebrand to Molecule AI under github.com/Molecule-AI/molecule-monorepo. Brand: Starfire → Molecule AI. Slug: starfire / agent-molecule → molecule. Env vars: STARFIRE_* → MOLECULE_*. Go module: github.com/agent-molecule/platform → github.com/Molecule-AI/molecule-monorepo/platform. Python packages: starfire_plugin → molecule_plugin, starfire_agent → molecule_agent. DB: agentmolecule → molecule. History truncated; see public repo for prior commits and contributor attribution. Verified green: go test -race ./... (platform), pytest (workspace-template 1129 + sdk 132), vitest (canvas 352), build (mcp). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
84 lines
3.8 KiB
Markdown
84 lines
3.8 KiB
Markdown
# Constraints & Rules
|
|
|
|
Key design rules and invariants that must be followed throughout the codebase.
|
|
|
|
## 1. The Platform Never Routes Agent Messages
|
|
|
|
A2A messages go workspace-to-workspace **directly**. The platform only handles:
|
|
- **Discovery** — resolving workspace URLs
|
|
- **Registry** — knowing what workspaces exist
|
|
|
|
## 2. Postgres Is Source of Truth, Redis Is Ephemeral
|
|
|
|
If Redis is wiped, workspaces re-register on next heartbeat and state is restored. Nothing critical lives only in Redis.
|
|
|
|
## 3. structure_events Is Append-Only
|
|
|
|
Never `UPDATE` or `DELETE` rows in this table. The `workspaces` table is the mutable projection. See [Event Log](../architecture/event-log.md).
|
|
|
|
## 4. workspace-template Is Generic
|
|
|
|
It contains **no business logic**. All business logic lives in `workspace-configs-templates/`. The template reads config files at startup — it does not know what kind of workspace it is until it loads config.
|
|
|
|
## 5. Bundles Do Not Contain Secrets
|
|
|
|
API keys, passwords, and credentials are **never** serialized into bundle JSON. The provisioner injects them from the host environment when spinning up a workspace container.
|
|
|
|
## 6. No Auth for MVP
|
|
|
|
The platform API has no authentication. All endpoints are open. This is intentional — the project follows the n8n Community Edition model. Auth is added in a separate SaaS wrapper (`molecule-cloud`).
|
|
|
|
## 7. org_id Is Omitted from MVP Schema
|
|
|
|
Removed entirely for MVP simplicity. Added in the SaaS migration for multi-tenancy.
|
|
|
|
## 8. Tier Determines Provisioner, Not Behavior
|
|
|
|
The workspace code is the same regardless of tier. The tier only affects how the workspace is deployed:
|
|
- Docker flags
|
|
- host access level and isolation boundary
|
|
- Resource allocation
|
|
|
|
See [Workspace Tiers](../architecture/workspace-tiers.md).
|
|
|
|
## 9. The Hierarchy IS the Topology
|
|
|
|
There is no manual connection wiring. Communication is derived from the `parent_id` hierarchy:
|
|
- Siblings can talk to each other
|
|
- Parents can talk to children (and vice versa)
|
|
- No skipping levels
|
|
|
|
The org chart IS the access control policy. See [Communication Rules](../api-protocol/communication-rules.md).
|
|
|
|
## 10. Discovery-Time Auth for MVP
|
|
|
|
Direct A2A calls between workspaces are unauthenticated in MVP. Access control is enforced at discovery time via `CanCommunicate()`. Post-MVP adds platform-issued signed tokens scoped to caller/target pairs. See [A2A Protocol — Authentication](../api-protocol/a2a-protocol.md#authentication-between-workspaces).
|
|
|
|
## 11. Secrets in Postgres, Encrypted
|
|
|
|
Workspace secrets (API keys, credentials) are stored in Postgres with AES-256 encryption at the application layer. The encryption key comes from the `SECRETS_ENCRYPTION_KEY` environment variable. Secrets are never included in bundles, never logged, never exposed via API responses.
|
|
|
|
## 12. Last-Write-Wins for MVP
|
|
|
|
Concurrent canvas modifications from multiple clients use last-write-wins. No optimistic locking or CRDTs for MVP.
|
|
|
|
## 13. Security Headers on All Responses
|
|
|
|
The platform applies HTTP security headers via middleware (`platform/internal/middleware/securityheaders.go`):
|
|
- `X-Content-Type-Options: nosniff`
|
|
- `X-Frame-Options: DENY`
|
|
- `X-XSS-Protection: 1; mode=block`
|
|
|
|
These are applied after CORS middleware on every response.
|
|
|
|
## 14. No Exposed Database Ports
|
|
|
|
Postgres and Redis must not expose host ports. They communicate exclusively over the internal Docker network (`molecule-monorepo-net`). Use `docker compose exec` for direct access during development.
|
|
|
|
## Related Docs
|
|
|
|
- [SaaS Upgrade Path](../product/saas-upgrade.md) — How auth and multi-tenancy are added
|
|
- [Bundle System](../agent-runtime/bundle-system.md) — Why bundles exclude secrets
|
|
- [Event Log](../architecture/event-log.md) — The append-only rule
|
|
- [Communication Rules](../api-protocol/communication-rules.md) — Hierarchy = access control
|