SaaS Platform Engine

A production-ready multi-tenant SaaS backend framework built with Java 21 & Spring Boot 3.

https://saas-platform-engine-production.up.railway.app

Demo credentials:

• Email: admin@demo.com
• Password: Demo1234!

Every SaaS product needs the same plumbing before it can ship its first feature: tenant isolation, authentication, roles, billing, audit trails, feature flags and usage limits. SaaS Platform Engine is that plumbing, done properly — a fork-and-go Spring Boot backend where multi-tenancy is enforced at the query level, permissions are declarative annotations, and metering/auditing happen off the request thread via AOP. It's built for backend developers who want to start a SaaS from a foundation that already behaves like a production system, not a tutorial.

                                ┌────────────────────────────────────────────────┐
                                │                 Spring Boot App                │
 HTTP Request                   │                                                │
──────────────▶ TenantFilter ──▶│ JwtAuthFilter ──▶ Controller ──▶ Service ──▶ JPA│──▶ PostgreSQL
   (header /      resolves      │  verifies RS256    @Requires-     @Transactional│    (row-level
    subdomain)    tenant into   │  JWT, overrides    Permission                  │     tenant_id
                  ThreadLocal   │  tenant from claim  @TrackUsage                │     isolation)
                                │                     @FeatureFlagRequired       │
                                │                          │                     │
                                │            ┌─────────────┼─────────────┐       │
                                │            ▼             ▼             ▼       │
                                │      AuditService  MeteringService  FlagCache ─┼──▶ Redis
                                │      (async pool)  (async pool +               │    (flags:* cache,
                                │            │        @Scheduled agg.)           │     refresh:* tokens)
                                │            ▼             ▼                     │
                                │       audit_logs   usage_records/summaries    │
                                └────────────────────────────────────────────────┘

• Multi-tenancy — row-level isolation (tenant_id on every table), tenant resolved from X-Tenant-ID header, JWT claim or subdomain; pluggable TenancyStrategy (shared-schema / schema-per-tenant)
• Auth — RS256 JWT access tokens (15 min) + single-use rotating refresh tokens in Redis (7 days)
• RBAC — system roles (OWNER/ADMIN/MEMBER/SUPER_ADMIN), tenant-scoped custom roles (PRO+), declarative @RequiresPermission("billing:manage") enforcement via AOP
• Billing — plans, subscriptions, invoices, Stripe checkout/portal/webhooks with signature verification; automatic mock mode without credentials
• Audit log — every action captured asynchronously with before/after snapshots, IP and user agent; paginated, filterable API
• Feature flags — per-tenant flags with percentage rollout, Redis cache (60s TTL) with write-through invalidation, @FeatureFlagRequired gate that 404s disabled endpoints
• Usage metering — @TrackUsage AOP: synchronous plan-limit check (429 on breach), async usage recording, per-minute aggregation job
• Onboarding — one transaction creates tenant + owner + FREE subscription and returns tokens immediately
• Super admin — cross-tenant management: list, inspect usage, override plan, suspend
• Demo dashboard — single-file dark SPA with live usage rings, flag toggles, billing and a built-in API explorer
• Ops — Flyway migrations, Testcontainers test suite, multi-stage Docker build, GitHub Actions CI, Railway deployment

1. Row-level multi-tenancy over schema-per-tenant (default). Shared schema with a tenant_id column keeps operations cheap: one connection pool, one migration run, trivial cross-tenant analytics for the platform operator. The trade-off is that isolation lives in code, so the rule here is structural: repositories only expose finder methods that require a tenantId parameter, and the tenant always comes from the verified JWT — a spoofed X-Tenant-ID header can never switch an authenticated caller's tenant. SeparateSchemaTenancy exists behind the same TenancyStrategy interface for customers who contractually need physical separation.

2. RS256 (asymmetric) JWT instead of HS256. With HS256 every service that verifies tokens can also mint them — one leaked shared secret compromises the platform. With RS256 the private key never leaves the auth component; API gateways, sidecar services or a future microservice split verify with the public key only. For a SaaS designed to grow past one deployable, asymmetric is the correct default even while the app is still a monolith.

3. AOP for audit, metering and permissions. @RequiresPermission, @TrackUsage and @TrackAudit keep cross-cutting policy out of business logic: a controller method declares what it needs, aspects decide how it's enforced. Audit and metering writes are handed to dedicated executors — a slow audit insert can never add latency to a user request, and losing one audit row on crash is an accepted trade-off documented in code.

4. Redis cache for feature flags — bounded staleness, explicit invalidation. Flag reads happen on hot paths, so they're served from Redis (flags:{tenant}:{key}, 60s TTL) instead of hitting PostgreSQL per request. Writes delete the cache key, so toggles apply immediately on the instance that made the change and within 60 seconds everywhere else — a deliberate consistency/performance trade-off. If Redis is down, evaluation falls back to the database: flags degrade in latency, not in correctness.

git clone https://github.com/addictcode/saas-platform-engine.git
cd saas-platform-engine
docker compose up --build

Open http://localhost:8080 and click Try Demo (admin@demo.com / Demo1234!).

Create your own tenant:

curl -X POST http://localhost:8080/onboarding/start \
  -H 'Content-Type: application/json' \
  -d '{"companyName":"Acme Inc","email":"you@acme.dev","password":"Sup3rSecret!","fullName":"Jane Doe"}'

Login and call the API:

TOKEN=$(curl -s -X POST http://localhost:8080/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@demo.com","password":"Demo1234!"}' | jq -r .accessToken)

curl http://localhost:8080/api/v1/tenant/usage -H "Authorization: Bearer $TOKEN"

Toggle a feature flag (takes effect immediately):

curl -X PATCH http://localhost:8080/api/v1/flags/beta_dashboard \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"enabled":true,"rolloutPct":25}'

com.saasengine
├── config/          Security, CORS, Redis, JPA, async executors, Stripe gateway selection
├── multitenancy/    TenantContext (ThreadLocal), TenantFilter, interceptor, isolation strategies
├── auth/            JWT (RS256) issuing/verification, refresh token rotation, login/register
├── onboarding/      Tenant provisioning, slug generation
├── domain/
│   ├── tenant/      Tenant aggregate
│   ├── user/        Users, invitations, seat limits
│   ├── rbac/        Roles, permissions, grants
│   ├── subscription/ Plans and subscriptions
│   ├── billing/     Invoices, checkout, Stripe gateway (real + mock)
│   ├── audit/       Async audit trail
│   ├── featureflags/ Flags with Redis cache + rollout
│   └── metering/    Usage records, limits, aggregation job
├── api/             REST controllers (v1)
├── admin/           Cross-tenant super admin API
└── shared/          Exceptions, @RequiresPermission/@TrackUsage/@TrackAudit + aspects

./mvnw test        # requires Docker (Testcontainers spins up PostgreSQL + Redis)

• Email verification & password reset flows
• OAuth2 social login (Google/GitHub) per tenant
• Outbound webhook system with retries and HMAC signing
• Usage analytics dashboard (time-series rollups)
• Terraform provider for tenant provisioning

MIT