multitenantsaasplatformwithexternalintegrations-7f7k45/README.md

# 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:**
```bash
pip install -r requirements.txt
```

2. **Set up environment variables:**
```bash
# 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:**
```bash
# Create the database directory
mkdir -p /app/storage/db

# Run Alembic migrations
alembic upgrade head
```

4. **Start the main application:**
```bash
python main.py
```

5. **Start mock external services (optional):**
```bash
# 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
```bash
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
```bash
POST /api/v1/auth/login
{
  "email": "admin@example.com",
  "password": "securepassword"
}
```

### User Management
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Install ruff
pip install ruff

# Format code
ruff format .

# Lint and fix
ruff check --fix .
```

### Testing
```bash
# 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.