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 it needs — PostgreSQL, RabbitMQ, MailHog — and run 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
docker compose up -d
./mvnw spring-boot:run -Pdev
  • compose.yaml — infrastructure only (IDE workflow)
  • compose.container.yaml — full stack incl. 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 everything — all services, both SPAs, Nginx, Prometheus, Grafana, Loki. Add three lines to hosts and you're done.

git clone https://github.com/IQKV/microservices-platform.git
cd microservices-platform
cp .env.example .env
./demo.sh          # Linux / macOS
.\demo.ps1         # Windows (PowerShell)
  • 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 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

Uses depends_on: condition: service_healthy throughout — DB & RabbitMQ → IAM → Billing & Audit → Gateway → UIs.

Expected: 2–4 min with images pulled. Each service awaits :8081/actuator/health/readiness before dependents start.

View Source Live Demo
Multi-Tenancy Architecture

Hybrid Tenancy Model: B2B + B2C

One codebase, two deployment models. Switch via a single config flag — no code changes required.

Multi-Tenant Mode (B2B SaaS)

Multiple companies, single deployment, complete data isolation.

  • Schema-Per-Tenant — dedicated PostgreSQL schema per company
  • Complete Isolation — data, migrations, and queries are tenant-scoped
  • Tenant Context — auto-resolved 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 in one default workspace — no tenancy complexity needed.

  • Default Workspace — all users join a pre-configured default tenant
  • Simplified UX — no tenant selection or org management screens
  • Same Infrastructure — 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
Switch models with one config change — no code modifications required.
Multi-Tenant (B2B) Single-Tenant (B2C)
Technology Stack

Enterprise Java Without Overhead

Production-grade technologies, proven track records. Enterprise patterns without unnecessary complexity.

Backend Stack

  • Java 25 — records, pattern matching, text blocks, switch expressions
  • Spring Boot 4.x — modern Spring 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, OAuth2 Client, method security
  • BCrypt — password hashing with strength 12
  • JWKS Endpoint — public key distribution for JWT validation
  • Two-Layer Revocation — JTI denylist + global signout timestamp
  • OAuth2 / OIDC — Google, GitHub, Microsoft, tenant-scoped enterprise SSO
  • Stripe & Lemon Squeezy SDKs — pluggable payment gateway adapters; webhook signature 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
  • MinIO — S3-compatible object storage
  • DbGate — web-based database administration

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

Five Core SaaS Services

RESTful APIs at /api/v1/iam, /api/v1/billing, /api/v1/audits, /api/v1/cms, and a reactive gateway. Each service is independently deployable with its own Helm chart, CI/CD pipeline, and PostgreSQL database.

IAM Service

Identity & Access Management — foundation-iam-service

  • Self-service signup with async tenant provisioning; signup-by-invitation (72h tokens)
  • JWT RS256 — 15-min access / 7-day refresh; JWKS at /.well-known/jwks.json; token exchange for tenant switching
  • OAuth2 / OIDC federation — Google, GitHub, Microsoft, plus tenant-scoped custom OIDC providers for enterprise SSO
  • Per-tenant roles: TENANT_OWNER, ADMIN, MEMBER; users may belong to multiple tenants
  • Email verification, rate-limited password reset; brute-force lockout (5 attempts / 15 min)
  • JTI denylist + global signout; platform admin auth and operator APIs
  • Account linking / unlinking and platform-admin forced unmerge for linked external identities
  • Avatar uploads via presigned S3/MinIO two-phase 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, payment gateway webhooks (signature-verified)
  • Aggregated Swagger UI; security response headers on every response
Spring WebFluxOAuth2 RSReactive

Billing Service

Payments & Subscriptions — foundation-billing-service

  • PaymentGatewayPort abstraction (Strategy pattern) — Stripe and Lemon Squeezy adapters; swap gateways via deploy-time config without touching business logic
  • Auto-provisions gateway customer on tenant.provisioned event (RabbitMQ)
  • billing_settings per tenant — billing email, tax ID/VAT, billing portal session
  • Plan catalog CRUD (platform admin); subscription checkout and management (tenant owner)
  • Idempotent webhook ingestion; publishes lifecycle events to the platform event bus
  • Refunds API — initiate and list per tenant; platform admin refund overview
  • Grafana dashboard: revenue, active subscriptions, webhook health
StripeLemon SqueezyHexagonalPostgreSQL

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, …) into a unified AuditRecord
  • 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

CMS Service

Content Management — foundation-cms-service

  • Static page management with publishing status (draft/published)
  • Multi-language support with en-US fallback
  • Hierarchical content structure with parent/child pages
  • SEO-friendly metadata (title, description, Open Graph, canonical URLs)
  • Tenant isolation with schema-per-tenant architecture
  • Event-driven content lifecycle (cms.page.created/updated/deleted)
Multi-TenantSEOPostgreSQL
Included UI Applications

Four Production UI Apps

React 19, TypeScript, Mantine UI, TanStack Router & Query, Astro, VitePress, Feature-Sliced Design, Vitest, Playwright. SPAs proxy to the API gateway in dev and support runtime public/config.js overrides without rebuilds.

Tenant App — foundation-ui-app

Tenant-scoped SPA via X-Tenant-ID and tenant JWTs — sign-in, team management, account, billing.

  • Sign-in with tenant discovery, social login, and enterprise SSO entry; sign-up with provisioning poll
  • Forgot/reset password and email verification flows
  • Accept invitations (/invite/:token) — new and existing users
  • Dashboard, team list, send/revoke invitations (TENANT_OWNER)
  • My Account — profile, password, organizations and roles, connected accounts
  • Billing — Stripe or Lemon Squeezy portal, active subscription, plan catalog, billing info, refunds
  • Tenant settings — organization metadata editing
  • Security settings — TENANT_OWNER SSO configuration for issuer, client, scopes, and enabled flag
  • In-app notifications with WebSocket push; notification bell UI
  • Silent token refresh, 30-min inactivity sign-out, light/dark theme, Lingui i18n
Tenant JWTPublic-facingLingui i18n

Planned: additional locales and deeper OIDC test hardening.

Platform Admin — foundation-ui-platform-admin

PLATFORM_ADMIN operators — users, orgs, invitations, subscriptions, plans. Platform-scoped tokens (tenant_id null).

  • Admin sign-in via POST /v1/iam/auth/admin/signin
  • Dashboard — count cards: users, organizations, active subscriptions
  • Users — paginated list, detail, edit profile, set password, platform authority tab, OIDC identities tab
  • Organizations — overview, members, billing, subscriptions, refunds tabs
  • Invitations — propose, edit, revoke across all tenants; read-only plan catalog
  • Subscriptions — global list + detail; cancel, pause, reactivate, quantity update; refunds list and detail
  • Announcements — create, edit, publish, delete with multi-lingual support
  • Audit logs — global view across all tenants
  • In-app notifications with WebSocket; operator account & password; forced unmerge for linked identities
PLATFORM_ADMINInternalmantine-datatable

Planned: change-plan / discount actions, impersonation, system health & jobs, MRR/ARR metrics.

SaaS Landing Kit — foundation-ui-saas-landing-kit

Astro + React + Tailwind CSS + shadcn/ui landing page with integrated platform authentication.

  • Astro for static site generation; React for interactive components
  • Tailwind CSS + shadcn/ui components
  • Integrated login/logout with the platform IAM
  • Responsive; SEO-friendly
AstroTailwindshadcn/ui

Documentation Website — foundation-docs-website

VitePress documentation site with user guides, platform overview, and quick start — deploy alongside your application.

  • VitePress for fast static site generation
  • User guides, quick start, architecture docs
  • Responsive; SEO-friendly
VitePressDocumentationStatic Site
Four UI apps — tenant SPA, admin SPA, landing page, docs — all on the same platform APIs.
Live Demo
Why This Platform

The Kitchen, Not Just the Recipe

Most SaaS boilerplates show you how to cook, but you still have to build the kitchen. This platform is the kitchen — everything a real B2B product needs before a single line of 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 a shared table with a tenant_id column. When an enterprise asks "is our data completely separate?", the answer is yes, by design.

Infrastructure Included

Kubernetes Helm charts, Drone CI/CD, Prometheus + Grafana — all configured and ready. Indie boilerplates ship app code only. Not here.

Grows Beyond a Monolith

IAM, Gateway, Billing, and Audit are separate services from day one. Add domain services without touching the core. When you outgrow a single process, the architecture is already there.

Enterprise-Ready from Day One

Schema isolation, RBAC, brute-force protection, token revocation, audit logs, async provisioning — table stakes for B2B sales that most boilerplates can't offer.

Zero Vendor Lock-In

No Vercel, Supabase, or AWS Cognito. No platform fees that scale with revenue. Deploy anywhere. Apache 2.0 — fork it, modify it, ship it. No strings attached.

B2B or B2C — One Codebase

Start single-tenant for B2C, flip a config flag for multi-tenant B2B. No code changes, no migration, no rewrite.

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

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

SAML / SCIM

OAuth2/OIDC social login and tenant-scoped enterprise SSO are included. SAML and SCIM are still not included out of the box; teams that need them on day one can integrate Jackson or similar.

Java Backend

Services are Java 25 + Spring Boot. Teams on Node, Python, PHP, or .NET can treat them as black-box infrastructure, but there is an onboarding cost.

Early Stage

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

Who It's For

The Gap Between Indie and Enterprise

Indie boilerplates target solo founders who don't need data isolation or Kubernetes. Enterprise platforms need six-figure budgets. There's nothing in between that's open, self-hostable, infrastructure-complete, and free. This is that third option.

Small Engineering Teams

3–15 engineers building a real B2B product. You need proper infrastructure but can't spend 4–6 months building it before writing actual product code.

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

B2B SaaS Founders

Enterprise customers will ask about data isolation, self-hosting, and security. You need answers beyond "we use Supabase row-level security."

  • Schema-per-tenant — 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

Traffic is growing, the codebase is hard to change, and you need to split things up without a full rewrite.

  • Adopt IAM and Gateway independently
  • Migrate billing 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. Drone CI, Docker multi-stage builds, Helm charts, three environments.

1. VerifyCode

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

2. PublishArtifacts

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

3. Docker Images

Multi-stage builds. Feature branches tagged by branch name, releases by semver. Pushed to container registry.

4. Kubernetes Deployment

Helm-based deployments. WIP auto-deploy, feature/release promotion (staging → production), and atomic rollback.

8. ReleasePackage

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

Container Infrastructure

Kubernetes 1.19+ · Helm 3.2+. Three environments: local (Docker Compose), staging, production. 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 — JUnit 5 + Mockito
  • Integration — Testcontainers with real PostgreSQL
  • Architecture — ArchUnit boundary validation
  • E2E — Playwright (Chrome, Firefox, Safari)
  • Frontend — Vitest + Testing Library + MSW
  • Contract — OpenAPI 3.0 specification compliance

Static Analysis Gates

  • SonarQube — quality gates, security vulns, 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
Full-Stack Development Services

Included SPAs + Custom Frontends

Use the included foundation-ui-app and foundation-ui-platform-admin, or build additional dashboards on the same REST APIs. One backend, multiple frontends.

Modular API Backend

OpenAPI 3.0 specs for all endpoints. JWT authentication works with any client — web, mobile, or third-party integrations.

  • 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, mobile apps — 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 the same backend APIs
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