Multi-Tenancy Architecture

Hybrid Tenancy Model: B2B + B2C

One codebase, two deployment models. Multi-tenant for B2B SaaS (schema-per-tenant isolation) or single-tenant for B2C applications (all users in default workspace). Switch via simple configuration flag — no code changes required.

Multi-Tenant Mode (B2B SaaS)

Serve multiple companies from a single deployment with complete data isolation. Each tenant gets dedicated PostgreSQL schema.

  • Schema-Per-Tenant - Each company gets dedicated PostgreSQL schema
  • Complete Isolation - Data, migrations, and queries are tenant-scoped
  • Tenant Context - Automatic tenant resolution from JWT claims
  • Shared Infrastructure - Cost-effective resource utilization
  • Independent Migrations - Liquibase per-tenant schema versioning
  • Async Provisioning - RabbitMQ-based tenant creation workflow

Single-Tenant Mode (B2C Applications)

All users belong to one default workspace. Perfect for B2C applications where tenancy is not needed.

  • Default Workspace - All users join pre-configured default tenant
  • Simplified UX - No tenant selection, no organization management
  • Same Infrastructure - Uses identical schema isolation architecture
  • Configuration Switch - Set platform.rolloutMode: SINGLE_TENANT
  • Bootstrap at Startup - Default tenant provisioned automatically
  • Same Codebase - No code changes, just configuration
Hybrid Tenancy Model

Choose the right deployment model for your business. Multi-tenant for B2B SaaS serving multiple companies, or single-tenant for B2C applications with all users in one workspace. Switch between models with a simple configuration change — no code modifications required.

Multi-Tenant (B2B) Single-Tenant (B2C)
Technology Stack

Enterprise Java Without Overhead

Production-grade technologies with proven track records. Enterprise patterns and tooling without unnecessary complexity. Built for long-term maintainability and team productivity.

Backend Stack

  • Java 25 - Records, pattern matching, text blocks, switch expressions
  • Spring Boot 4.x - Modern Spring framework with reactive support
  • Spring Cloud Gateway - Reactive API gateway with WebFlux
  • PostgreSQL 17 - Schema-per-tenant isolation, ACID-compliant
  • MyBatis 3.x - XML mappers, no JPA; tenant-aware schema routing
  • springdoc-openapi - Swagger UI per service; aggregated at gateway
  • RabbitMQ - Event-driven messaging with topic exchange

Security & Auth

  • JWT RS256 - JJWT library with RSA PEM keys
  • Spring Security - OAuth2 Resource Server, method security
  • BCrypt - Password hashing with strength 12
  • JWKS Endpoint - Public key distribution for JWT validation
  • Two-Layer Revocation - JTI denylist + global signout timestamp
  • Stripe SDK - Payment processing and webhook verification

DevOps & Infrastructure

  • Docker - Multi-stage builds with Docker Compose
  • Kubernetes - Container orchestration with Helm charts
  • Drone CI/CD - 10-stage automated pipeline
  • Traefik - Reverse proxy and load balancer
  • Liquibase - Database migrations and schema versioning
  • ShedLock - Distributed job locking with JDBC provider

Observability & Testing

  • Prometheus & Grafana - Metrics collection and dashboards
  • Loki & Promtail - Log aggregation and querying
  • Micrometer - Application metrics with custom tags
  • Structured Logging - JSON logs with Logstash encoder
  • JUnit 5 & Testcontainers - Integration testing with real databases
  • ArchUnit - Architecture validation and boundary enforcement
Platform Components

Three Core SaaS Services

Complete SaaS foundation with RESTful APIs at /api/v1/iam, /api/v1/billing, and a reactive gateway in front. Each service is independently deployable with its own Helm chart, CI/CD pipeline, and PostgreSQL database. Bootstrap new services from the microservice project layout template — same stack, quality gates, and Docker/Kubernetes wiring.

IAM Service

Identity & Access Management — foundation-iam-service

  • Self-service signup with async tenant provisioning (poll until ACTIVE)
  • JWT RS256 — 15-minute access tokens, 7-day refresh; JWKS at /.well-known/jwks.json
  • Per-tenant authorities: TENANT_OWNER, ADMIN, MEMBER
  • Signup-by-invitation (72h tokens), email verification, password reset
  • Platform admin auth (/auth/admin/signin) and operator APIs
  • JTI denylist + global signout; brute-force lockout (5 attempts / 15 min)
  • Schema-per-tenant PostgreSQL + Liquibase; ROLLOUT_MODE for B2B/B2C
Multi-TenantSchema IsolationRabbitMQ

Gateway Service

Reactive API Gateway — foundation-gateway-service

  • Spring Cloud Gateway (WebFlux) — single entry point for IAM and Billing
  • RS256 JWT validation via IAM JWKS; configurable public paths
  • Strips spoofable X-User-* / X-Tenant-ID headers before auth
  • Propagates user, authorities, tenant, and X-Correlation-ID downstream
  • Routes: IAM API, Billing API, Stripe webhooks (signature-verified)
  • Aggregated Swagger UI; security response headers on every response
Spring WebFluxOAuth2 RSReactive

Billing Service

Payments & Subscriptions — foundation-billing-service

  • PaymentGatewayPort abstraction — Stripe adapter implemented
  • Auto-provisions Stripe customer on tenant.provisioned (RabbitMQ)
  • billing_settings per tenant — billing email, tax ID/VAT, gateway sync
  • Plan catalog (tenant + platform admin); subscription read APIs
  • Idempotent Stripe webhooks; lifecycle events to the event bus
  • Subscriptions and invoices managed on the payment gateway side
StripeHexagonalPostgreSQL
Included UI Applications

Two Production React SPAs

Ship with tenant-facing and platform-admin frontends — React 19, TypeScript, Mantine UI, TanStack Router & Query, Feature-Sliced Design, Vitest, and Playwright. Both apps proxy to the API gateway in development and support runtime public/config.js overrides without rebuilds.

Tenant App — foundation-ui-app

Workspace members sign in, manage their team, and maintain their account — scoped to a single tenant via X-Tenant-ID and tenant-scoped JWTs.

  • Sign-in with tenant discovery; sign-up with provisioning poll
  • Forgot/reset password and email verification flows
  • Accept invitations (/invite/:token) — new and existing users
  • Dashboard, team member list, send/revoke invitations (TENANT_OWNER)
  • My Account — profile, password, organizations and roles
  • Silent token refresh, 30-minute inactivity sign-out, light/dark theme
Tenant JWTPublic-facingLingui i18n

Planned: billing self-service, tenant settings, member role editing.

Platform Admin — foundation-ui-platform-admin

Operators with PLATFORM_ADMIN manage users, organizations, invitations, subscriptions, and plans. Platform-scoped tokens (tenant_id null).

  • Admin sign-in via POST /v1/iam/auth/admin/signin
  • Dashboard — count cards for users, organizations, active subscriptions
  • Users — paginated list, detail, edit profile, set password
  • Organizations — overview, members, billing settings tabs
  • Invitations — propose, edit, revoke; plan catalog CRUD
  • Subscriptions (read-only); operator account & password
PLATFORM_ADMINInternalmantine-datatable

Planned: platform actions, system health, audit log, advanced metrics.

Same APIs, Two Audiences

The tenant app calls IAM tenant APIs. Platform admin calls operator /admin/* and billing admin endpoints. Deploy both SPAs behind the gateway — or build additional frontends on the same REST surface.

Live Demo
DevOps Pipeline

Kubernetes-Native CI/CD Pipeline

10-stage automated pipeline from code push to production. Each microservice runs in Docker containers with dedicated Helm charts. Environment-specific configurations for local, staging, and production deployments.

1. VerifyCode

Code coverage (JaCoCo), static analysis (SonarQube, PMD, SpotBugs), Testcontainers integration tests with PostgreSQL 17.

2. PublishArtifacts

Maven artifacts to Nexus repository. GitHub releases with automated changelog generation.

3. Docker Images

Multi-stage Docker builds with optimized images. Feature branch images tagged with branch name, release images with semver. Pushed to container registry.

4. Kubernetes Deployment

Helm-based deployments to Kubernetes clusters. WIP auto-deploy, feature promotion, release promotion (staging/production), and rollback capabilities with atomic deployments.

8. ReleasePackage

Automated semantic versioning and GitHub release creation. Slack notifications for all pipeline events.

Container Infrastructure

Kubernetes 1.19+ with Helm 3.2+. Docker containers for all services. Three environments: local (Docker Compose), staging, production. Environment-specific Helm values. Supports multi-tenant and single-tenant deployments.

Quality Assurance

Automated Quality Without Overhead

Multi-layer testing with automated gates in every pipeline run. Enterprise tooling configured for productivity, not bureaucracy.

Multi-Layer Testing

  • Unit Tests - JUnit 5 + Mockito for service logic
  • Integration Tests - Testcontainers with real PostgreSQL
  • Architecture Tests - ArchUnit for boundary validation
  • E2E Tests - Playwright (Chrome, Firefox, Safari)
  • Frontend Tests - Vitest + Testing Library + MSW
  • Contract Tests - OpenAPI 3.0 specification compliance

Static Analysis Gates

  • SonarQube - Quality gates, security vulnerabilities, code smells
  • PMD - High-priority rule violations block pipeline
  • SpotBugs - Bug pattern detection with custom exclusions
  • CheckStyle - Google Java Style Guide enforcement
  • JaCoCo - Per-service coverage thresholds
  • Maven Enforcer - Dependency and version consistency
Quality Tools & Automation
Code Quality
  • SonarQube - Quality gates
  • PMD - Rule violations
  • SpotBugs - Bug detection
  • CheckStyle - Style enforcement
Testing Frameworks
  • JUnit 5 - Unit testing
  • Mockito - Mocking framework
  • Testcontainers - Integration tests
  • ArchUnit - Architecture validation
Frontend Quality
  • Vitest - Unit testing
  • Testing Library - Component tests
  • Playwright - E2E testing
  • MSW - API mocking
Coverage & Reporting
  • JaCoCo - Java coverage
  • Vitest Coverage - Frontend coverage
  • SonarQube Reports - Unified dashboard
  • Pipeline Gates - Automated enforcement
Full-Stack Development Services

Included SPAs + Custom Frontends

Start with foundation-ui-app (tenant workspace) and foundation-ui-platform-admin (operator console), or build additional dashboards on the same REST APIs — customer portals, analytics, mobile apps. One backend, multiple frontends for different user roles.

Modular API Backend

RESTful APIs with OpenAPI 3.0 specifications. JWT authentication ready for any client. Build web dashboards, mobile apps, or third-party integrations on the same backend.

  • RESTful APIs — OpenAPI 3.0 specs for all endpoints
  • JWT Authentication — Works with any frontend framework
  • Event-Driven — RabbitMQ for real-time updates
  • Multi-Client Ready — One backend, multiple frontends

Custom Dashboard Development

We build tailored dashboards for your vertical — admin panels, customer portals, analytics dashboards, mobile apps. Different interfaces for different user roles, all powered by the same API backend.

  • • Admin Dashboards — Tenant management, user admin, billing
  • • Customer Portals — Self-service interfaces for end users
  • • Analytics Dashboards — Real-time metrics and reporting
  • • Mobile Apps — iOS/Android with same backend APIs
Dashboard Examples: One Backend, Multiple Frontends

Build different dashboards for different user roles and use cases — all consuming the same RESTful APIs.

Admin Dashboard

Tenant management, user administration, billing overview, system monitoring, audit logs

Customer Portal

Self-service interface, profile management, subscription billing, feature access, support tickets

Analytics Dashboard

Real-time metrics, usage analytics, revenue reports, tenant growth, custom KPIs

Mobile App

iOS/Android native apps, same JWT authentication, same APIs, optimized mobile UX

Our Technology Expertise
Backend APIs
  • • Java / Spring Boot
  • • Node.js / NestJS
  • • PostgreSQL / MongoDB
  • • RESTful + OpenAPI 3.0
Frontend Frameworks
  • • React 19 + TypeScript
  • • Angular + Material UI
  • • Mantine / TanStack
  • • Feature-Sliced Design
DevOps & Cloud
  • • Kubernetes / Helm
  • • Docker / CI/CD
  • • AWS / Azure / GCP
  • • Infrastructure as Code
Quality & Testing
  • • Vitest + Testing Library
  • • Playwright E2E tests
  • • Code quality gates
  • • Performance optimization
Build Your SaaS Product With Us
Open Source & Community

Built in the Open, Powered by Community

This platform is 100% open source under Apache 2.0 license. Use it freely, modify it, contribute back. We welcome developers, architects, and SaaS builders to join us in making enterprise-grade infrastructure accessible to everyone.

Free & Open Source

  • Apache 2.0 License — Use commercially, modify, distribute freely
  • Full Source Access — Every line of code on GitHub
  • No Vendor Lock-In — You own your deployment and data
  • Production Ready — Battle-tested in real SaaS applications
  • Active Development — Regular updates and improvements
View on GitHub

Join the Community

We believe great infrastructure should be accessible to everyone. Whether you're building your first SaaS or your tenth, you can help make this platform better.

  • Report Issues — Found a bug? Let us know on GitHub
  • Contribute Code — Submit PRs for features or fixes
  • Improve Docs — Help others understand the platform
  • Share Knowledge — Write tutorials, create examples
  • Spread the Word — Star the repo, share with your network
Report Issue Submit PR
Open Source, Professional Support Available

Use the platform for free, or hire us to build custom features, provide training, or handle deployment. Your choice.

Learn About Custom Development