Multi-Tenant SaaS Platform with External Integrations

A comprehensive backend system that combines multi-tenant SaaS platform features with external API integration capabilities. Built with Python, FastAPI, and SQLite.

Features

Part A: Multi-Tenant Platform (60%)

• ✅ Multi-tenant data isolation using database-level security
• ✅ JWT-based authentication with role management (Super Admin, Org Admin, User, Viewer)
• ✅ RESTful API endpoints for user and organization operations
• ✅ Audit logging for all data modifications
• ✅ API rate limiting and input validation
• ✅ Security middleware with XSS/CSRF protection

Part B: External Integration Engine (40%)

• ✅ Webhook processing from multiple external services
• ✅ Async event handling with retry logic and failure recovery
• ✅ External API calls with proper error handling
• ✅ Data synchronization between external services and internal data
• ✅ Integration health monitoring and status tracking

Advanced Features (Bonus)

• ✅ Circuit Breaker Pattern for external API calls
• ✅ Bulk Operations for handling batch webhook events efficiently
• ✅ Idempotency ensuring duplicate webhook processing is handled gracefully
• ✅ Security Headers and input validation middleware

Architecture

Database Schema

• Organizations: Multi-tenant isolation boundary
• Users: With role-based access control
• Audit Logs: Complete activity tracking
• External Integrations: Configuration for external services
• Webhook Events: Async event processing queue
• Integration Health: Service health monitoring

External Services

Three mock external services are included:

1. User Management Service (Port 8001)
2. Payment Service (Port 8002)
3. Communication Service (Port 8003)

Quick Start

Prerequisites

• Python 3.8+
• SQLite (included)
• Redis (optional, for advanced rate limiting)

Installation

1. Install dependencies:

pip install -r requirements.txt

2. Set up environment variables:

# Create .env file (optional)
SECRET_KEY=your-secret-key-change-in-production
WEBHOOK_SECRET=webhook-secret-key
REDIS_URL=redis://localhost:6379/0

3. Run database migrations:

# Create the database directory
mkdir -p /app/storage/db

# Run Alembic migrations
alembic upgrade head

4. Start the main application:

python main.py

5. Start mock external services (optional):

# Terminal 1
python mock_services/user_service.py

# Terminal 2  
python mock_services/payment_service.py

# Terminal 3
python mock_services/communication_service.py

API Documentation

Base URL

• Main Service: http://localhost:8000
• API Documentation: http://localhost:8000/docs
• Health Check: http://localhost:8000/api/v1/health

Authentication

Register Organization & Admin User

POST /api/v1/auth/register
{
  "email": "admin@example.com",
  "username": "admin",
  "password": "securepassword",
  "first_name": "Admin",
  "last_name": "User",
  "organization_name": "Example Corp",
  "organization_domain": "example.com",
  "organization_subdomain": "example"
}

Login

POST /api/v1/auth/login
{
  "email": "admin@example.com",
  "password": "securepassword"
}

User Management

# Get users (Admin only)
GET /api/v1/users/
Authorization: Bearer <token>

# Create user (Admin only)
POST /api/v1/users/
Authorization: Bearer <token>
{
  "email": "user@example.com",
  "username": "user",
  "password": "password",
  "organization_id": 1,
  "role": "USER"
}

# Update user
PUT /api/v1/users/{user_id}
Authorization: Bearer <token>

# Delete user (Admin only)
DELETE /api/v1/users/{user_id}
Authorization: Bearer <token>

Organization Management

# Get organization info
GET /api/v1/organizations/me
Authorization: Bearer <token>

# Update organization (Admin only)
PUT /api/v1/organizations/me
Authorization: Bearer <token>

# Get organization stats
GET /api/v1/organizations/me/stats
Authorization: Bearer <token>

Webhook Processing

# Webhook endpoints for external services
POST /api/v1/webhooks/user/{organization_id}
POST /api/v1/webhooks/payment/{organization_id}
POST /api/v1/webhooks/communication/{organization_id}

# Get webhook statistics (Admin only)
GET /api/v1/webhooks/stats
Authorization: Bearer <token>

# Trigger manual webhook processing (Admin only)
POST /api/v1/webhooks/process
Authorization: Bearer <token>

Integration Management

# Get integrations (Admin only)
GET /api/v1/integrations/
Authorization: Bearer <token>

# Sync data from external services (Admin only)
POST /api/v1/integrations/sync/users
POST /api/v1/integrations/sync/payments
POST /api/v1/integrations/sync/communications
POST /api/v1/integrations/sync/all
Authorization: Bearer <token>

# Check integration health (Admin only)
GET /api/v1/integrations/health
Authorization: Bearer <token>

Security Features

Multi-Tenant Data Isolation

• Database-level isolation using organization_id
• Row-level security in all queries
• API endpoints scoped to user's organization

Authentication & Authorization

• JWT tokens with configurable expiration
• Role-based access control (RBAC)
• Password hashing using bcrypt
• Protected routes with dependency injection

API Security

• Rate limiting (100 requests/minute by default)
• Input validation and sanitization
• XSS/CSRF protection headers
• Request size limiting
• SQL injection prevention

Webhook Security

• HMAC signature verification
• Duplicate event detection (idempotency)
• Retry logic with exponential backoff
• Error handling and logging

Integration Features

Circuit Breaker Pattern

• Automatic failure detection
• Service degradation handling
• Configurable failure thresholds
• Health check recovery

Async Processing

• Background task processing
• Retry logic for failed operations
• Dead letter queue handling
• Performance monitoring

Health Monitoring

• Real-time service health checks
• Response time tracking
• Error rate monitoring
• Integration status reporting

Configuration

Environment Variables

# Security
SECRET_KEY=your-secret-key-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Database
DB_DIR=/app/storage/db
SQLALCHEMY_DATABASE_URL=sqlite:///[DB_DIR]/db.sqlite

# External Services
EXTERNAL_USER_SERVICE_URL=http://localhost:8001
EXTERNAL_PAYMENT_SERVICE_URL=http://localhost:8002
EXTERNAL_COMMUNICATION_SERVICE_URL=http://localhost:8003

# Rate Limiting
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60
REDIS_URL=redis://localhost:6379/0

# Webhooks
WEBHOOK_SECRET=webhook-secret-key

# Circuit Breaker
CIRCUIT_BREAKER_FAILURE_THRESHOLD=5
CIRCUIT_BREAKER_TIMEOUT=60

Development

Code Quality

• Linting: Ruff for code formatting and linting
• Type Checking: Built-in Python type hints
• Testing: Pytest framework ready
• Documentation: OpenAPI/Swagger auto-generated

Running with Ruff

# Install ruff
pip install ruff

# Format code
ruff format .

# Lint and fix
ruff check --fix .

Testing

# Install test dependencies
pip install pytest pytest-asyncio

# Run tests
pytest

Project Structure

├── app/
│   ├── api/
│   │   ├── endpoints/       # API route handlers
│   │   └── v1/             # API version grouping
│   ├── core/               # Core functionality
│   │   ├── config.py       # Configuration settings
│   │   ├── deps.py         # Dependencies/middleware
│   │   └── security.py     # Authentication logic
│   ├── db/                 # Database configuration
│   ├── integrations/       # External service integrations
│   │   ├── external_apis/  # API clients
│   │   └── webhooks/       # Webhook handlers
│   ├── middleware/         # Custom middleware
│   ├── models/             # SQLAlchemy models
│   ├── schemas/            # Pydantic schemas
│   ├── services/           # Business logic
│   └── utils/              # Utility functions
├── alembic/                # Database migrations
├── mock_services/          # Mock external services
├── storage/                # Application storage
│   └── db/                 # SQLite database
├── tests/                  # Test suite
├── main.py                 # Application entry point
├── requirements.txt        # Python dependencies
└── README.md              # This file

Performance Considerations

Database

• SQLite with WAL mode for concurrent access
• Proper indexing on foreign keys and search fields
• Connection pooling for production use

API Performance

• Async/await for I/O operations
• Background task processing
• Response caching for static data
• Pagination for large datasets

Integration Performance

• Circuit breaker pattern prevents cascading failures
• Retry logic with exponential backoff
• Connection pooling for external APIs
• Health checks to avoid dead services

Monitoring & Observability

Audit Logging

• All user actions logged with context
• IP address and user agent tracking
• Resource-level change tracking
• Searchable audit trail

Health Monitoring

• Service health endpoints
• Integration status tracking
• Performance metrics collection
• Error rate monitoring

Webhook Processing

• Event processing statistics
• Retry attempts tracking
• Success/failure rates
• Processing time metrics

Production Deployment

Environment Setup

1. Set proper environment variables
2. Configure Redis for rate limiting
3. Set up proper SSL/TLS certificates
4. Configure reverse proxy (nginx/Apache)

Security Hardening

1. Change default secret keys
2. Enable HTTPS only
3. Configure proper CORS origins
4. Set up rate limiting
5. Enable security headers

Monitoring

1. Set up application logging
2. Configure health check monitoring
3. Set up alerts for failures
4. Monitor performance metrics

License

This project is created for assessment purposes.