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

# Cameleer SaaS — Phase Roadmap

> Implementation phases derived from the [SaaS Platform PRD](../specs/2026-03-29-saas-platform-prd.md).
> 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 → cameleer-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 cameleer-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 cameleer-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 cameleer-server
- cameleer-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 cameleer-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