Get Running in Minutes

Two Ways to Start Locally

Working on a single service? Spin up just its infrastructure and run from your IDE. Want the full platform end-to-end? One command starts everything — all four services, both React SPAs, and the complete observability stack.

Per-Service Development

Each service ships its own compose.yaml. Start only the infrastructure that service needs — PostgreSQL, RabbitMQ, MailHog — and run the service from your IDE. No other services required.

git clone https://github.com/IQKV/foundation-iam-service.git
cd foundation-iam-service

cp .env.example .env.local

# Start infrastructure only
docker compose up -d

# Run service from IDE or CLI
./mvnw spring-boot:run -Pdev
  • compose.yaml — infrastructure only (IDE workflow)
  • compose.container.yaml — full stack including service build
  • Isolated named volumes and network per service
  • Swagger UI at :8080/swagger-ui.html
IDE Friendly Fast Iteration No Cross-Service Deps

Full Demo Stack

One command starts the entire platform — all services, both SPAs, Nginx reverse proxy, and the full observability stack (Prometheus, Grafana, Loki). Add three lines to your hosts file and you're done.

git clone https://github.com/IQKV/microservices-platform.git
cd microservices-platform

cp .env.example .env

# Linux / macOS
./demo.sh

# Windows (PowerShell)
.\demo.ps1
  • Tenant app → http://app.iqkv.local
  • Platform admin → http://admin.iqkv.local
  • API + Swagger → http://api.iqkv.local
  • Grafana, Prometheus, MailHog via subpaths
End-to-End Observability Included One Command
One-time hosts file setup (demo stack)
# /etc/hosts  (Linux/macOS)
# C:\Windows\System32\drivers\etc\hosts  (Windows)

127.0.0.1  api.iqkv.local
127.0.0.1  admin.iqkv.local
127.0.0.1  app.iqkv.local
Startup order & timing

The demo stack uses depends_on: condition: service_healthy throughout. Services start in dependency order — databases and RabbitMQ first, then IAM, then Billing and Audit, then Gateway, then UIs.

Expected startup time: 2–4 minutes with images already pulled. Each Java service waits for its readiness probe at :8081/actuator/health/readiness before dependents start.

View Source Live Demo
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

Four Core SaaS Services

Complete SaaS foundation with RESTful APIs at /api/v1/iam, /api/v1/billing, /api/v1/audits, 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); signup-by-invitation (72h tokens)
  • JWT RS256 — 15-min access tokens, 7-day refresh; JWKS at /.well-known/jwks.json; token exchange for tenant switching
  • Per-tenant authorities: TENANT_OWNER, ADMIN, MEMBER; users can belong to multiple tenants
  • Email verification, password reset (rate-limited); brute-force lockout (5 attempts / 15 min)
  • JTI denylist + global signout; platform admin auth and operator APIs
  • Avatar uploads via two-phase presigned S3/MinIO flow; old avatars auto-deleted
  • In-app notifications — persisted + real-time WebSocket push (STOMP/SockJS)
  • Site-wide announcements with multi-lingual support; async fan-out to all users
  • Schema-per-tenant PostgreSQL + Liquibase; ROLLOUT_MODE for B2B/B2C switch
Multi-TenantSchema IsolationRabbitMQWebSocket

Gateway Service

Reactive API Gateway — foundation-gateway-service

  • Spring Cloud Gateway (WebFlux) — single entry point for all platform services
  • RS256 JWT validation via IAM JWKS; configurable public paths bypass auth
  • Strips spoofable X-User-* / X-Tenant-ID / X-Audit-* headers before auth — prevents identity spoofing
  • Propagates user, authorities, tenant, and X-Correlation-ID downstream
  • Captures client IP and User-Agent as X-Audit-IP / X-Audit-UA for audit context
  • Per-route, per-tenant request metrics; Grafana dashboard included
  • Routes: IAM API, Billing API, Stripe webhooks (signature-verified)
  • Aggregated Swagger UI; security response headers (X-Frame-Options, X-XSS-Protection, etc.) on every response
Spring WebFluxOAuth2 RSReactive

Billing Service

Payments & Subscriptions — foundation-billing-service

  • PaymentGatewayPort abstraction (Strategy pattern) — Stripe adapter implemented; swap gateways without business logic changes
  • Auto-provisions Stripe customer on tenant.provisioned event (RabbitMQ)
  • billing_settings per tenant — billing email, tax ID/VAT, Stripe Customer Portal session
  • Plan catalog CRUD (platform admin); subscription checkout and management (tenant owner)
  • Idempotent Stripe webhook ingestion; publishes lifecycle events to the platform event bus
  • Refunds API — initiate and list refunds per tenant; platform admin refund overview
  • Grafana dashboard with business KPIs: revenue, active subscriptions, webhook health
StripeHexagonalPostgreSQL

Audit Service

Centralized Activity Logging — foundation-audit-service

  • Passive observer — binds to the iqkv.events exchange; zero code changes in domain services for basic auditing
  • Transforms domain events (UserEvent, TenantEvent, etc.) into a unified AuditRecord format
  • Enriches records with client IP and User-Agent propagated from the Gateway
  • Dedicated PostgreSQL database — high-volume logging isolated from business transactions
  • SPI pattern (foundation-audit-spi) — plug in Elasticsearch or custom SIEM backends
  • Secured admin search API — paginated, filterable by user, tenant, and action
Passive ConsumptionSPI PatternPostgreSQL
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. Architecture follows Feature-Sliced Design with automated boundary tests.

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
  • Billing — portal access, active subscription, plan catalog, billing info, refunds
  • Tenant settings — organization metadata editing
  • In-app notifications with WebSocket support; notification bell UI
  • Silent token refresh, 30-minute inactivity sign-out, light/dark theme, Lingui i18n
Tenant JWTPublic-facingLingui i18n

Planned: member role editing, additional locales.

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, subscriptions, refunds tabs
  • Invitations — propose, edit, revoke across all tenants; plan catalog CRUD
  • Subscriptions (read-only global list + detail); refunds list and detail
  • Announcements — create, edit, publish, delete with multi-lingual translation support
  • Audit logs — global audit log view across all tenants
  • In-app notifications with WebSocket support; operator account & password
PLATFORM_ADMINInternalmantine-datatable

Planned: platform actions (ban/unlock/impersonation), system health & jobs, advanced metrics (MRR/ARR).

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
Why This Platform

The Kitchen, Not Just the Recipe

Most SaaS boilerplates give you a recipe book. They show you how to cook, but you still have to build the kitchen yourself — the plumbing, the wiring, the infrastructure. This platform is the kitchen. Everything a real B2B product needs before you can write a single line of your actual business logic.

Capability Indie Boilerplates
ShipFast, Supastarter,
SaaS Pegasus, SaaSykit…		 Enterprise Platforms
Liferay, Entando,
dotCMS…		 IQ Key Value
Free / Apache 2.0
Price $199 – $499 one-time Enterprise contracts Free forever
License Proprietary Proprietary / LGPL Apache 2.0
Multi-tenancy Shared DB, tenant_id column Virtual instances / logical Schema-per-tenant
True data isolation
Data isolation
Shared tables		 Logical / DB-level
PostgreSQL schema per tenant
Kubernetes + Helm
App code only		 Partial / vendor-managed
Full Helm charts included
Microservices split
Monolith		 OSGi bundles / modules
IAM · Gateway · Billing · Audit
Async provisioning Varies
RabbitMQ event-driven
API Gateway Reverse proxy only
JWT auth + context propagation
Audit logs
Most have none		 Varies
Centralized audit service
Vendor lock-in Vercel / Supabase / AWS High (vendor cloud) None
Self-hosted Partial Yes (complex)
Any cloud or on-premise
Real Data Isolation

Every customer's data lives in its own PostgreSQL schema — not mixed in a shared table with a tenant_id column. When an enterprise customer asks "can our data be kept completely separate?", the answer is yes, by design, not by workaround.

Infrastructure Included

Kubernetes Helm charts, Drone CI/CD pipeline, Prometheus + Grafana dashboards — all configured and ready. Indie boilerplates ship application code only. You still have to figure out the infrastructure yourself. Not here.

Grows Beyond a Monolith

IAM, Gateway, Billing, and Audit are separate services from day one. Add your own domain services without touching the core. When your product outgrows a single process, the architecture is already there — you're extending, not rewriting.

Enterprise-Ready from Day One

Schema isolation, RBAC, brute-force protection, token revocation, audit logs, and async provisioning are table stakes for B2B sales. Most boilerplates can't offer them at all. Your enterprise prospects will ask — you'll have the answers.

Zero Vendor Lock-In

No Vercel. No Supabase. No AWS Cognito. No platform fees that scale with your revenue. Deploy to any cloud or your own servers. Apache 2.0 means you own it permanently — fork it, modify it, ship it. No strings attached.

B2B or B2C — One Codebase

Start single-tenant for a B2C app, flip a config flag to go multi-tenant for B2B. No code changes, no migration, no rewrite. The only platform that lets you change your business model without changing your infrastructure.

Honest Gaps — What This Platform Doesn't Do (Yet)

We'd rather tell you upfront than have you find out halfway through evaluation.

SSO / SAML

Not included out of the box. Planned as an extension. Teams that need SAML on day one can integrate Jackson or a similar library — the IAM service is designed to accept it.

Java Backend

The platform services are Java 25 + Spring Boot. Teams on Node, Python, PHP, or .NET can treat them as black-box infrastructure and build their own services on top of the event bus — but there is an onboarding cost.

Early Stage

ShipFast, SaaS Pegasus, and SaaSykit have paying customers and battle-tested codebases. This platform is actively developed and production-ready, but the community is still growing.

Who It's For

The Gap Between Indie and Enterprise

Indie boilerplates are built for solo founders who want to ship fast and don't need data isolation or Kubernetes. Enterprise platforms are built for companies with six-figure budgets and a dedicated Java team. There is nothing in between that is open, self-hostable, infrastructure-complete, and free. This platform is that third option.

Small Engineering Teams

3–15 engineers building a real B2B product for real business customers. You need proper infrastructure but can't afford to spend 4–6 months building it before writing a single line of your actual product.

  • Skip months of IAM, billing, and gateway work
  • Start with production-grade infrastructure
  • Add your domain services on top of the event bus
  • Own everything — no platform dependency

B2B SaaS Founders

Building a product where enterprise customers are in the picture. They'll ask about data isolation, self-hosting, and security. You need answers that go beyond "we use Supabase row-level security."

  • Schema-per-tenant isolation — the real answer to "is our data separate?"
  • Self-hosted deployment — pass security reviews
  • RBAC + audit logs — enterprise procurement checklist
  • No vendor lock-in — your customers will ask

Teams Outgrowing a Monolith

You started with a boilerplate or a monolith and it's working — until it isn't. Traffic is growing, the codebase is getting hard to change, and you need to split things up without a full rewrite.

  • Adopt the IAM and Gateway services independently
  • Migrate billing to the Billing service at your own pace
  • Plug into the event bus without touching existing code
  • Apache 2.0 — fork and adapt to your needs
Every B2B product has to solve the same four problems before writing a line of actual business logic.

Who are you? Which company do you belong to? Are you paying? Can you talk to the system? This platform answers all four — out of the box, for free.

View Source 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