☁️ Cloud Native SaaS Platform

Enterprise-grade multi-tenant SaaS control plane with RBAC, API keys, billing simulation, audit logs, analytics, Docker, Kubernetes, and AWS/Terraform deployment assets.

Overview • Features • Screenshots • Architecture • Quick Start • API • Troubleshooting

---

📌 Overview

This is a production-oriented SaaS reference platform that demonstrates how an enterprise backend can manage tenants, users, subscriptions, API keys, rate limits, audit logs, analytics, and billing simulation through a secure FastAPI control plane.

It is designed as a portfolio-grade backend/platform engineering project, not a tutorial scaffold. The application includes a FastAPI-served browser dashboard, Swagger/OpenAPI documentation, PostgreSQL persistence, Redis-backed rate limiting support, Docker, Kubernetes manifests, Terraform AWS templates, GitHub Actions, Jenkins, tests, and security scanning.

The system includes two realistic operating modes:

• Tenant flow: tenant owners register, authenticate, generate API keys, upgrade subscriptions, generate invoices, and view tenant analytics.
• Platform admin flow: seeded platform administrators provision tenants, list tenants, and inspect platform-wide metrics.

---

✨ Features

🏢 SaaS Core Multi-tenant data model Tenant onboarding Tenant-scoped users Tenant isolation checks Subscription plans Billing simulation

🔐 Security & Access JWT authentication HTTP Bearer Swagger auth Platform admin guardrails RBAC-ready schema Hashed API keys Audit logging

🚀 Platform Engineering FastAPI backend Built-in dashboard PostgreSQL + Redis Docker Compose Kubernetes manifests AWS Terraform templates

---

🧱 Tech Stack

FastAPI Backend API	Python Application Runtime	PostgreSQL Primary Database	Redis Caching & Rate Limits
Docker Containerization	Kubernetes Deployment	AWS Cloud Architecture	Terraform Infrastructure as Code
Pytest Testing	Bandit Security Scan	GitHub Actions CI/CD	Jenkins Pipeline

---

📸 Screenshots

---

🏗️ Architecture

flowchart TD
    A[Browser Dashboard / Swagger Client] --> B[FastAPI Application]
    B --> C[Authentication Service]
    B --> D[Tenant Service]
    B --> E[Subscription & Billing Service]
    B --> F[API Key Service]
    B --> G[Analytics Service]
    B --> H[Audit Log Service]
    B --> I[(PostgreSQL)]
    B --> J[(Redis)]
    K[GitHub Actions / Jenkins] --> L[Docker Image]
    L --> M[Kubernetes / AWS]

Loading

🔄 End-to-End Workflow

User Opens FastAPI Dashboard or Swagger
        ↓
User Registers a Tenant Owner OR Logs in as Seeded Platform Admin
        ↓
FastAPI Issues JWT Bearer Token
        ↓
Protected APIs Validate Token and Tenant Scope
        ↓
Tenant Owners Manage API Keys, Subscriptions, Billing, and Analytics
        ↓
Platform Admins Provision and List Tenants
        ↓
Audit Logs Capture Sensitive Actions
        ↓
Metrics and Usage Data Power SaaS Analytics

System Flow

Step	What Happens
1	Tenant owner registers an organization and user account
2	User logs in and receives a JWT access token
3	Protected endpoints validate Authorization: Bearer <token>
4	Tenant-scoped APIs isolate user activity by tenant_id
5	API keys are generated once and stored as hashes
6	Billing simulation uses subscription and usage data
7	Audit logs record platform and tenant operations
8	Platform admins manage global tenant operations

---

🗃️ Database Design

erDiagram
    TENANTS ||--o{ USERS : owns
    TENANTS ||--o{ SUBSCRIPTIONS : has
    TENANTS ||--o{ API_KEYS : issues
    TENANTS ||--o{ INVOICES : receives
    TENANTS ||--o{ USAGE_EVENTS : records
    USERS ||--o{ USER_ROLES : assigned
    ROLES ||--o{ USER_ROLES : maps
    ROLES ||--o{ ROLE_PERMISSIONS : grants
    PERMISSIONS ||--o{ ROLE_PERMISSIONS : included
    TENANTS ||--o{ AUDIT_LOGS : generates

Loading

Key database tables:

Table	Purpose
tenants	SaaS customer organizations
users	Tenant-scoped and platform users
roles	RBAC role definitions
permissions	Permission catalog
user_roles	User-to-role mapping
subscriptions	Active and historical subscription plans
api_keys	Hashed tenant API keys
invoices	Billing simulation records
usage_events	Usage and analytics events
audit_logs	Compliance and action history
rate_limit_events	Request throttling history

---

📁 Folder Structure

cloud-native-saas-platform/
├── backend/
│   ├── app/
│   │   ├── api/                 # FastAPI route modules
│   │   ├── core/                # Config and security helpers
│   │   ├── db/                  # SQLAlchemy session and seed data
│   │   ├── middleware/          # Rate limiting middleware
│   │   ├── models/              # Database models
│   │   ├── schemas/             # Pydantic schemas
│   │   ├── services/            # Business services
│   │   ├── static/              # FastAPI-served dashboard
│   │   └── main.py              # App factory
│   ├── tests/                   # Unit and integration tests
│   ├── Dockerfile
│   └── requirements.txt
├── docs/
│   ├── architecture.md
│   ├── api-spec.md
│   ├── deployment.md
│   ├── security.md
│   └── screenshots/
├── infra/
│   ├── k8s/                     # Kubernetes manifests
│   └── terraform/               # AWS infrastructure templates
├── data/
│   └── sample-requests.http
├── .github/workflows/ci.yml
├── docker-compose.yml
├── Jenkinsfile
├── README.md
└── LICENSE

---

⚡ Quick Start

Prerequisites

Requirement	Version
Python	3.11+
Docker	Optional
PostgreSQL	Optional with Docker Compose
Redis	Optional with Docker Compose
Git	Any recent version

Run Locally

cd backend
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Open:

http://localhost:8000

Swagger:

http://localhost:8000/docs

Seeded Platform Admin

The application automatically creates this platform administrator during startup:

Tenant Slug: platform
Email: admin@saas.dev
Password: Admin123!

Use this account to test platform-only endpoints such as:

GET  /api/v1/tenants
POST /api/v1/tenants
GET  /api/v1/analytics/platform-summary

Run Tests

cd backend
pytest

Run Quality Checks

ruff check app tests
bandit -r app -c ../bandit.yaml

Run with Docker

docker compose up --build

Open:

http://localhost:8000

---

🔌 API Reference

Register Tenant Owner

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"tenant_name":"Acme Cloud","tenant_slug":"acme-cloud","email":"owner@example.com","full_name":"Taranjyot Singh","password":"Password123!"}'

Login

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"tenant_slug":"acme-cloud","email":"owner@example.com","password":"Password123!"}'

Swagger Authorization

After login, copy the access_token, click Authorize in Swagger, and paste:

Bearer <access_token>

Read Current User

curl http://localhost:8000/api/v1/users/me \
  -H "Authorization: Bearer <access_token>"

Create API Key

curl -X POST http://localhost:8000/api/v1/api-keys \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"production-client"}'

Generate Invoice

curl -X POST http://localhost:8000/api/v1/billing/generate-invoice \
  -H "Authorization: Bearer <access_token>"

Platform Admin: List Tenants

curl http://localhost:8000/api/v1/tenants \
  -H "Authorization: Bearer <platform_admin_access_token>"

---

🛡️ Security Design

✅ Included JWT bearer authentication Password hashing Platform admin authorization Tenant-scoped data access API key hashing Redis-ready rate limiting Audit logs CORS configuration Pydantic validation Bandit security scanning

🚧 Production Extensions Refresh token rotation Secrets Manager integration Row-level security policies SSO / OIDC federation Fine-grained permission checks WAF and API Gateway throttling Centralized SIEM export mTLS for service-to-service traffic

---

📈 Monitoring Strategy

Area	Implementation
Health	/api/v1/health
Readiness	/api/v1/ready
Logs	Structured application logging ready for CloudWatch
Auditability	audit_logs table for sensitive actions
Usage Tracking	usage_events for billing and analytics
Rate Limiting	Redis-ready middleware and headers
Cloud Monitoring	AWS CloudWatch-ready deployment design
Future Extension	Prometheus/Grafana dashboards

---

🔁 CI/CD

GitHub Actions

The workflow validates the backend through:

Install dependencies
        ↓
Run Ruff linting
        ↓
Run Pytest test suite
        ↓
Run Bandit security scan
        ↓
Build Docker image

Jenkins

The included Jenkinsfile demonstrates a production-style pipeline:

Checkout
  → Install
  → Lint
  → Test
  → Security Scan
  → Docker Build
  → Kubernetes Deploy

---

☁️ Deployment Architecture

flowchart TD
    A[Developer Push] --> B[GitHub Actions / Jenkins]
    B --> C[Docker Image]
    C --> D[Container Registry]
    D --> E[AWS EKS / ECS]
    E --> F[Application Load Balancer]
    E --> G[(Amazon RDS PostgreSQL)]
    E --> H[(Amazon ElastiCache Redis)]
    E --> I[CloudWatch Logs]
    J[Terraform] --> E
    J --> G
    J --> H

Loading

The repository includes deployment assets for:

• Docker Compose local deployment
• Kubernetes manifests
• AWS infrastructure templates with Terraform
• CI/CD deployment flow

---

🧪 What This Project Demonstrates

Skill Area	Demonstrated Through
Backend Engineering	FastAPI routes, services, schemas, middleware
SaaS Architecture	Tenants, users, subscriptions, usage, billing
Security Engineering	JWT, API key hashing, admin-only endpoints
Platform Engineering	Control-plane dashboard and seeded admin flow
Cloud Engineering	Docker, Kubernetes, AWS/Terraform assets
DevSecOps	GitHub Actions, Jenkins, Ruff, Pytest, Bandit
Data Engineering	Usage events, analytics, billing aggregation
Observability	Health/readiness checks and audit logs

---

🧰 Troubleshooting

Tenant endpoints return 401 Unauthorized

You are not authenticated yet, or Swagger does not have your token.

Login first:

POST /api/v1/auth/login

Then click Authorize in Swagger and paste:

Bearer <access_token>

Tenant endpoints return 403 Platform admin required

This is expected if you are logged in as a normal tenant owner.

Use the seeded platform admin account:

Tenant Slug: platform
Email: admin@saas.dev
Password: Admin123!

Port 8000 is already in use

Stop the existing server or run on another port:

uvicorn app.main:app --reload --port 8001

Docker Compose cannot connect to Postgres

Rebuild and restart the full stack:

docker compose down -v
docker compose up --build

Swagger Authorize popup looks different than expected

This project uses HTTP Bearer auth, not OAuth password flow, because login requires tenant_slug, email, and password.

Paste the token like this:

Bearer eyJ...

---

🔄 Recommended Clean Rebuild

rm -f backend/*.db backend/test_saas.db
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pytest
ruff check app tests
bandit -r app -c ../bandit.yaml
uvicorn app.main:app --reload

---

🗺️ Roadmap

Priority	Improvement
High	Add refresh tokens and token revocation
High	Add granular permission enforcement per route
High	Add Alembic migrations
Medium	Add Prometheus metrics endpoint
Medium	Add Grafana dashboard JSON
Medium	Add tenant-level feature flags
Medium	Add background jobs for invoice generation
Low	Add SSO/OIDC login option
Low	Add SaaS admin React dashboard as optional frontend

---

📄 License

This project is licensed under the MIT License.

---

⚠️ Disclaimer

This project is built as a portfolio-grade reference implementation for backend, platform, cloud, and SaaS architecture demonstrations.

It is not intended to process real customer billing data, production credentials, or regulated personal information without additional hardening, compliance review, and cloud security controls.