Multi-tenant saas structure

[landywei]

Summary

Describe the problem and fix in 2–5 bullets:

• Problem: The service was single-tenant, lacking the ability to host multiple isolated organizations with their own workspaces and coding agents.
• Why it matters: This PR transforms the service into a multi-tenant SaaS platform, enabling scalable deployment for multiple users and organizations, each with isolated environments and advanced AI coding capabilities.
• What changed: Implemented a complete foundational multi-tenant SaaS platform including database schema, JWT authentication, container management, gateway proxy, health monitoring, API routes, a basic dashboard UI, and integration of a claude_code tool.
• What did NOT change (scope boundary): Advanced UI/UX, comprehensive billing/subscription features, or full Kubernetes deployment (currently uses Docker Compose for local setup).

Change Type (select all)

• Feature
• Bug fix
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related #

User-visible / Behavior Changes

• New multi-tenant SaaS platform with user signup, organization creation, and isolated environments.
• Organizations can provision and manage their own OpenClaw instances.
• Agents within an organization can utilize a new claude_code tool for autonomous coding tasks.
• A basic web dashboard is available for platform administration.

Security Impact (required)

• New permissions/capabilities? (Yes)
• Secrets/tokens handling changed? (Yes)
• New/changed network calls? (Yes)
• Command/tool execution surface changed? (Yes)
• Data access scope changed? (Yes)
• If any Yes, explain risk + mitigation:
  • Risk: Unauthorized access to org data/containers, privilege escalation, API key leakage.
  • Mitigation: JWT-based authentication, role-based access control, container isolation (Docker), environment variable injection for API keys, secure password hashing (bcrypt). Further hardening and auditing will be needed for production.

Repro + Verification

Environment

• OS: Linux/macOS (for Docker)
• Runtime/container: Node.js, Docker, PostgreSQL
• Model/provider: Claude (via Claude Code CLI)
• Integration/channel (if any): N/A
• Relevant config (redacted): JWT_SECRET, POSTGRES_URL, CONTAINER_PORT_RANGE_START, ANTHROPIC_API_KEY

Steps

1. Clone the repository.
2. Run pnpm install.
3. Set up required environment variables (e.g., JWT_SECRET, POSTGRES_URL).
4. Run docker-compose -f docker-compose.platform.yml up --build.
5. Access the dashboard at http://localhost:3000 (or configured port).
6. Sign up as a new user.
7. Create a new organization.
8. Provision and start the organization's container.

Expected

• Platform server starts successfully.
• PostgreSQL database is initialized.
• Dashboard is accessible.
• User can sign up, log in, create an org.
• Org container provisions and starts successfully.
• Org gateway is reachable via the platform proxy.
• All platform tests pass.

Actual

• All platform-specific TypeScript errors resolved.
• All platform unit tests pass.
• All platform-specific linting issues resolved.

Evidence

• Failing test/log before + passing after (TypeScript and lint errors fixed, then tests passed)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • Code compiles without platform-specific TypeScript errors.
  • All platform unit tests pass.
  • Linting issues resolved for platform code.
• Edge cases checked:
  • Type handling for req.params.userId (string vs string[]).
  • jsonwebtoken payload typing.
  • Error handling for log.error with unknown types.
• What you did not verify:
  • End-to-end functionality of the Docker containers (provisioning, proxying, Claude Code execution).
  • Full UI interactivity beyond basic dashboard rendering.
  • Scalability or performance under load.
  • Security vulnerabilities beyond basic auth implementation.

Compatibility / Migration

• Backward compatible? (No)
• Config/env changes? (Yes)
• Migration needed? (No)
• If yes, exact upgrade steps: N/A

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: Revert this PR.
• Files/config to restore: Remove Dockerfile.platform, docker-compose.platform.yml, and the src/platform directory. Revert changes to package.json and pnpm-lock.yaml.
• Known bad symptoms reviewers should watch for:
  • Platform server failing to start.
  • Database connection issues.
  • Org container provisioning failures.
  • Auth failures (signup, login, token validation).
  • Proxying issues to org containers.
  • Claude Code tool not executing or returning results.

Risks and Mitigations

• Risk: Security vulnerabilities in auth or container isolation.
  • Mitigation: JWT best practices, bcrypt for passwords, Docker container isolation. Further security audits and penetration testing recommended for production.
• Risk: Resource exhaustion or performance issues with container management.
  • Mitigation: Configurable resource limits for containers (CPU, memory), health monitoring with auto-restart. Designed for future migration to Kubernetes for better scalability.
• Risk: ANTHROPIC_API_KEY leakage.
  • Mitigation: Injected as environment variable into isolated containers, not directly exposed in client-side code. Ensure secure storage in PostgreSQL.

  

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}