cameleer-saas/docs/superpowers/plans/2026-03-29-phase-roadmap.md

Cameleer SaaS — Phase Roadmap

Implementation phases derived from the SaaS Platform PRD. Each phase gets its own detailed implementation plan when it starts.

Principle: Each phase produces working, testable, deployable software. No phase requires a future phase to be useful.

---

Phase Dependency Graph

Phase 1: Foundation + Auth
    ↓
Phase 2: Tenants + Licensing
    ↓
Phase 3: K8s Infrastructure + Provisioning
    ↓
Phase 4: Camel Application Runtime
    ↓
Phase 5: Secrets + Config Management
    ↓
Phase 6: Observability Integration
    ↓
Phase 7: Billing & Metering
    ↓
Phase 8: Security Hardening + Self-Monitoring
    ↓
Phase 9: Frontend (React Shell)

Note: Phase 9 (Frontend) can be developed in parallel with Phases 3-8, building UI for each backend capability as it lands. Listed last because the backend API must exist first.

---

Phase 1: Foundation + Auth

PRD Sections: 3 (Architecture), 4 (Data Architecture), 5 (Identity & Access), 12 (Security — audit logging) Gitea Epics: #1 (Management Platform), #2 (Identity & Access), #11 (Security — audit only) Produces: Running Spring Boot 3 application with PostgreSQL, user registration, login, Ed25519 JWT issuance, RBAC (Owner/Admin/Developer/Viewer), and immutable audit logging.

Key deliverables:

• Maven project with modular package structure
• Docker Compose local dev environment (PostgreSQL)
• Flyway migrations for platform DB (users, roles, permissions, audit_log)
• Audit logging framework (append-only, no UPDATE/DELETE)
• User registration + password hashing (bcrypt)
• Ed25519 key pair generation + JWT signing/validation
• Login endpoint returning JWT
• Spring Security filter chain with JWT validation
• RBAC with predefined roles
• Health + readiness endpoints
• Dockerfile + Gitea Actions CI pipeline

Plan: 2026-03-29-phase-1-foundation-auth.md

---

Phase 2: Tenants + Licensing

PRD Sections: 4 (Data Architecture — tenants), 5 (IAM — team management), 10 (License & Feature Gating) Gitea Epics: #2 (Identity & Access — teams), #7 (License & Feature Gating) Depends on: Phase 1 Produces: Multi-tenant data model, tenant CRUD, team management, invite flow, Ed25519-signed license token generation, license API, and tenant-scoped auth (JWT carries tenant ID + role).

Key deliverables:

• Tenant entity + CRUD API
• Tenant membership (user-to-tenant with role)
• Team management API (create, invite, assign roles)
• Tenant context in JWT (tenant ID, role claims)
• License token generation (Ed25519-signed JWT with tier + feature flags + limits)
• License API endpoint (GET /api/license/{tenant})
• License lifecycle (generate on signup, regenerate on tier change)
• Tenant-scoped authorization (@PreAuthorize with tenant context)

---

Phase 3: K8s Infrastructure + Provisioning

PRD Sections: 6 (Tenant Provisioning), 11 (Networking & Tenant Isolation) Gitea Epics: #3 (Tenant Provisioning), #8 (Networking) Depends on: Phase 2 Produces: Automated tenant provisioning pipeline. Signup creates tenant → Flux HelmRelease generated → namespace provisioned → cameleer3-server deployed → PostgreSQL schema + OpenSearch index created → tenant ACTIVE. NetworkPolicies enforced.

Key deliverables:

• Provisioning state machine (idempotent, retryable)
• Flux HelmRelease CR generation from tenant config
• GitOps repo integration (commit HelmRelease CRs)
• Per-tenant PostgreSQL schema provisioning + credentials
• Per-tenant OpenSearch index template + credentials
• Readiness checking (poll tenant server health)
• Tenant lifecycle operations (suspend, reactivate, delete)
• K8s NetworkPolicy templates (default deny + allow rules)
• Helm chart for cameleer3-server tenant deployment

---

Phase 4: Camel Application Runtime

PRD Sections: 7 (Camel Application Runtime), 16 (Environments & Promotion) Gitea Epics: #5 (Camel Application Runtime), #10 (Environments & Promotion Pipeline) Depends on: Phase 3 Produces: Customers can upload a Camel JAR, platform builds an immutable container image with agent auto-injected, deploys to tenant namespace, promotes between environments.

Key deliverables:

• Application entity + CRUD API
• JAR upload endpoint with validation (type, size, checksum, Trivy scan)
• Dockerfile templating (distroless JRE + customer JAR + agent JAR + -javaagent)
• Container image build pipeline (buildx or Kaniko)
• Platform container registry integration (push, tag, list)
• K8s Deployment creation in tenant namespace
• Environment model (tier-based: Low=1, Mid=2, High+=unlimited)
• Promotion pipeline (same image tag, different config/secrets)
• Rollback (redeploy previous tag)
• Application lifecycle API (deploy, promote, rollback, scale, stop, delete, logs)
• Image signing (cosign) + SBOM generation

---

Phase 5: Secrets + Config Management

PRD Sections: 9 (Secrets Management), 7 (Application Deployment Page — config tab) Gitea Epics: #9 (Secrets Management) Depends on: Phase 4 Produces: Applications can use platform-managed secrets and external vault credentials. Per-environment config management.

Key deliverables:

• Platform-native secret store (encrypted in K8s Secrets via sealed-secrets/SOPS)
• Secret CRUD API (scoped per tenant + environment)
• K8s External Secrets Operator setup
• HashiCorp Vault integration (ExternalSecret CR generation)
• Secret injection into Camel app containers (env vars or mounted files)
• Secret rotation → rolling restart
• Per-environment config overlays (env vars, JVM options, application properties)
• Config change → rolling restart (no rebuild)
• Secret access audit logging
• Envelope encryption with per-tenant keys

---

Phase 6: Observability Integration

PRD Sections: 8 (Observability Integration) Gitea Epics: #6 (Observability Integration), #13 (Exchange Replay — gating only) Depends on: Phase 3 (server already deployed per tenant), Phase 2 (license for feature gating) Produces: Tenants see their cameleer3-server UI embedded in the SaaS shell. API gateway routes to tenant server. MOAT features gated by license tier.

Key deliverables:

• Ingress routing rules: /t/{tenant}/api/* → tenant's cameleer3-server
• cameleer3-server "managed mode" configuration (trust SaaS JWT, report metrics)
• Bootstrap token generation API
• MOAT feature gating via license (topology=all, lineage=limited/full, correlation=mid+, debugger=high+, replay=high+)
• Server UI embedding approach (iframe or reverse proxy with path rewriting)
• External agent connectivity (bootstrap tokens for customer-hosted apps)

---

Phase 7: Billing & Metering

PRD Sections: 14 (Billing & Metering) Gitea Epics: #4 (Billing & Metering) Depends on: Phase 3 (tenants exist), Phase 4 (runtime exists for metering) Produces: Stripe-integrated billing. Usage-based metering for shared tiers. Committed resource subscriptions for dedicated tiers.

Key deliverables:

• Stripe customer creation on tenant signup
• Stripe subscription management (usage-based and committed)
• Metrics collection pipeline (K8s metrics → aggregation)
• Usage aggregator (hourly, per-tenant, per-dimension: CPU, RAM, data volume)
• Stripe Usage Records API reporting
• Billing UI API (current usage, cost estimate, invoices, plan management)
• Metering pipeline reliability (idempotent, staleness alerting, reconciliation)
• Stripe webhook handling (payment events, subscription changes)

---

Phase 8: Security Hardening + Self-Monitoring

PRD Sections: 12 (Security & SOC 2), 13 (Platform Operations & Self-Monitoring) Gitea Epics: #11 (Security & SOC 2 — hardening), #12 (Platform Operations) Depends on: Phases 1-7 (hardens the full stack) Produces: Production-ready security posture and operational visibility. SOC 2 evidence collection. Platform self-monitoring with alerting.

Key deliverables:

• Container hardening: distroless base, read-only FS, Pod Security Standards restricted
• Image signing (cosign/sigstore) + SBOM generation in CI
• Trivy scanning in CI (block on critical CVEs)
• Per-tenant payload encryption (application-level, per-tenant keys)
• Audit log shipped to separate write-only sink
• Prometheus + Grafana deployment (self-monitoring)
• Loki for log aggregation
• Alertmanager + day-1 alert rules (10 critical alerts from PRD)
• Platform dashboards (overview, per-tenant, billing, infra, security)
• SLA reporting automation
• Falco or equivalent for runtime security scanning
• Breach detection alerting (anomalous API patterns, auth failures)

---

Phase 9: Frontend (React Shell)

PRD Sections: 15 (Management Platform UI) Gitea Epics: #1 (Management Platform — frontend) Depends on: Phase 1+ (builds incrementally as backend APIs land) Produces: Complete SaaS management UI built with @cameleer/design-system.

Key deliverables:

• Vite + React 19 + TypeScript project setup
• @cameleer/design-system integration (Gitea npm registry)
• Auth pages (login, register, invite acceptance)
• SaaS shell (navigation, tenant switcher, user menu)
• Dashboard (platform overview)
• Apps list + App deployment page (upload, config, secrets, status, logs, versions)
• Observability section (embedded cameleer3-server UI)
• Team management pages
• Settings pages (tenant config, SSO/OIDC, vault connections)
• Billing pages (usage, invoices, plan management)

---

Cross-Cutting Concerns (Woven Throughout)

These are not separate phases — they're applied in every phase:

• Audit logging — Every state-changing API logs to audit_log (Phase 1 establishes the framework)
• RBAC enforcement — Every endpoint checks permissions (Phase 1 establishes the framework)
• Input validation — Every API boundary validates input
• TLS — All connections encrypted (configured at infrastructure level)
• Testing — TDD: every feature has tests before implementation
• CI — Every commit runs tests, linting, scanning

---

Build Order Rationale

1. Phase 1 first because everything depends on auth + audit
2. Phase 2 before 3 because provisioning needs tenant + license entities
3. Phase 3 before 4 because runtime needs a provisioned namespace to deploy into
4. Phase 4 before 5 because secrets are injected into running apps
5. Phase 6 can overlap with 4-5 — server is already deployed in Phase 3, feature gating just needs license from Phase 2
6. Phase 7 after 4 because metering needs running apps to measure
7. Phase 8 after 1-7 because it hardens the complete stack
8. Phase 9 parallel with 3-8, building UI for each backend capability