Multi-tenant SaaS Platform Microservices - A comprehensive backend platform providing core services for building multi-tenant applications. This API-first platform handles authentication, billing, tenancy, and other common SaaS infrastructure needs.
A backend microservices platform that provides the foundational services needed by any multi-tenant SaaS application:
- Authentication & Authorization - JWT auth, RBAC, API keys, OAuth2
- Multi-Tenancy - Tenant isolation, onboarding, usage tracking
- Billing & Subscriptions - Invoicing, payments, Stripe integration, dunning
- Licensing - Feature flags, license management, plan enforcement
- Communications - Email, SMS, templates, notifications
- Analytics & Monitoring - Usage metrics, audit trails, observability
- Portals & Onboarding - Public tenant signup, partner portal, tenant portal
┌─────────────────────────────────────────────────────────────────┐
│ DotMac Platform Services │
│ (Control Plane for Multi-Tenant SaaS) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Auth │ │ Billing │ │ Tenant │ │
│ │ - JWT/RBAC │ │ - Invoices │ │ - Isolation│ │
│ │ - API Keys │ │ - Payments │ │ - Onboard │ │
│ │ - OAuth2 │ │ - Stripe │ │ - Usage │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Products │ │ Deployment │ │ Licensing │ │
│ │ - Catalog │ │ - Templates│ │ - Features │ │
│ │ - Modules │ │ - Provision│ │ - Plans │ │
│ │ - Versions │ │ - Scale │ │ - Enforce │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Comms │ │ Analytics │ │ Jobs │ │
│ │ - Email │ │ - Metrics │ │ - Async │ │
│ │ - SMS │ │ - Audit │ │ - Schedule │ │
│ │ - Templates│ │ - Traces │ │ - Workflows│ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
- JWT-based authentication with refresh tokens
- Role-Based Access Control (RBAC) with permissions
- API key management for service-to-service auth
- OAuth2 provider integration
- Multi-factor authentication support
- Complete tenant isolation
- Tenant onboarding automation
- Usage tracking and billing integration
- Custom domain verification
- Per-tenant configuration
- Product catalog management
- Subscription lifecycle management
- Invoice generation and PDF export
- Payment processing (Stripe integration)
- Dunning and collections
- Credit notes and refunds
- Dynamic feature flag management
- License activation and validation
- Plan-based feature enforcement
- Usage-based billing support
- Product Catalog - Define deployable SaaS products (e.g., Insights, Connect, Radius)
- Public Catalog API - Unauthenticated product listing for marketing/signup
- Deployment Templates - Kubernetes, Docker Compose, AWX/Ansible configurations
- Instance Provisioning - Automated tenant instance deployment
- Scaling & Lifecycle - Upgrade, suspend, resume, destroy operations
- Health Monitoring - Instance health checks and status tracking
- Email templates and sending
- SMS notifications
- Push notifications (PWA)
- In-app notifications
- Template management
- Usage analytics and metrics
- Audit trail logging
- Distributed tracing (OpenTelemetry)
- Real-time dashboards (REST + SSE)
- Public tenant signup with email verification
- Partner portal for referrals, commissions, statements
- Tenant portal for usage, billing, team, settings
- Python 3.12+
- PostgreSQL 15+
- Redis 7+
- Docker (optional)
# Clone the repository
git clone https://github.com/michaelayoade/dotmac-platform-services.git
cd dotmac-platform-services
# Install dependencies
poetry install
# Copy environment file
cp .env.example .env
# Run database migrations
poetry run alembic upgrade head
# Start the server
poetry run uvicorn dotmac.platform.main:app --reload# Start shared infrastructure (Postgres, Redis, MinIO, observability)
./scripts/infra.sh infra start
# Start the platform backend + admin UI
./scripts/infra.sh platform start
# Or build the image directly
docker build -t dotmac-platform-services .docs/INDEX.md- documentation map and entry pointsdocs/BACKEND_PRODUCTION_GUIDE.md- canonical backend production deployment guidedocs/architecture/INFRASTRUCTURE.md- reference for the shared infrastructure stack
Once running, access the API documentation at:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
- OpenAPI JSON: http://localhost:8000/openapi.json
Key environment variables:
# Database
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/dotmac
# Redis
REDIS_URL=redis://localhost:6379/0
# JWT
JWT_SECRET_KEY=your-secret-key
JWT_ALGORITHM=HS256
# Stripe (optional)
STRIPE_SECRET_KEY=sk_...
STRIPE_WEBHOOK_SECRET=whsec_...See .env.example for all configuration options.
This platform is designed to be consumed by other applications. Integration is done via:
- REST API - Standard HTTP endpoints with JWT auth
- API Keys - For service-to-service communication
- Webhooks - Event notifications to external systems
src/dotmac/platform/
├── auth/ # Authentication & RBAC
├── tenant/ # Multi-tenancy
├── billing/ # Billing & payments
├── partner_management/ # Partner program + portal APIs
├── user_management/ # User/team management
├── licensing/ # License management
├── platform_products/ # Platform product catalog (global)
├── deployment/ # Deployment orchestration
├── communications/ # Email, SMS, notifications
├── notifications/ # Notification channels/workflows
├── analytics/ # Usage analytics
├── audit/ # Audit trails
├── jobs/ # Async job processing
├── workflows/ # Workflow orchestration
├── data_import/ # Data import pipelines
├── data_transfer/ # Data export pipelines
├── webhooks/ # Webhook management
├── monitoring/ # Observability
├── resilience/ # Circuit breakers, service mesh
└── ...
# Run tests
poetry run pytest
# Run with coverage
poetry run pytest --cov=src/dotmac
# Lint
poetry run ruff check .
# Type check
poetry run mypy src/MIT License - see LICENSE for details.