Refactor: Plans & Quotas system (replace hardcoded demo user limits)

[victorsoriadrp]

Context

For the anchor video launch on 2026-07-06, we introduced a hardcoded quota check for the demo user (demo@archipulse.org) to prevent workspace pollution from viral traffic. This is pragmatic tech debt with a clear TODO in the code.

The proper architecture is a Plans + Quotas system that applies to all users, not just demo.

Current hardcoded implementation

• Location: workspace create handler
• Behavior: if user.email == demo@archipulse.org and workspace count >= 5, return 403 with CTA message
• Marked with TODO comment referencing this issue

Target architecture

Data model

• New table plans: name, max_workspaces, max_elements_per_ws, max_users, mcp_tools_allowed, etc.
• New relation users.plan_id (nullable, defaults to Free plan)
• Seed 4 default plans: Free, Demo, Team, Enterprise

Middleware

• Generic EnforceQuota(action string) middleware that:
  • Reads user's plan
  • Checks the relevant limit for the action
  • Returns 403 with contextual message if exceeded

Applied to

• Workspace creation (POST /workspaces)
• Element creation (POST /workspaces/{id}/elements)
• User invitation (POST /workspaces/{id}/members) — Team plan limit
• MCP tool invocations (optional, for tools requiring quota)

API

• GET /me/plan — returns current plan + usage
• GET /plans — lists available plans (admin only for editing)

UI

• Workspace list shows 3/5 workspaces used for quotad users
• Upsell CTAs when limit reached

Acceptance criteria

• Plans table migrated with 4 default plans seeded
• Users get default plan on signup
• Generic quota middleware in place
• Hardcoded demo user check removed
• Frontend shows usage indicators
• Documentation for plan configuration

Priority

Post-launch cleanup. Not blocking v0.7 features. Would fit v0.8 milestone or dedicated platform-plans work.

Related

• Business model in project memory: Self-hosted free forever, SaaS with tiered pricing coming
• Enterprise support planned for v1.0