Files

Eric Gullickson a052040e3a Initial Commit

2025-09-17 16:09:15 -05:00

38 KiB

Raw Blame History

Multi-Tenant SaaS Redesign Implementation Guide

Executive Summary

This document provides step-by-step instructions for transforming MotoVaultPro from a single-user application into a subdomain-based multi-tenant SaaS platform. The current implementation will become the "admin" tenant with full platform access, while new tenants get isolated application stacks.

Architecture Overview

Current State

Single-user application with user-scoped data isolation
Microservices: Application service + MVP Platform Services
Docker Compose development environment
Auth0 authentication with user-level access

Target State

Multi-tenant SaaS with subdomain routing
Admin tenant: admin.motovaultpro.com (current implementation)
New tenants: {tenant-id}.motovaultpro.com
Platform services: Shared infrastructure across all tenants
Per-tenant databases: Complete data isolation
Tenant-specific signup: With admin approval workflow

Key Technical Specifications

Subdomain Architecture

Landing Page: motovaultpro.com → Platform landing service
Admin Tenant: admin.motovaultpro.com → Admin application stack
Regular Tenants: {tenant-id}.motovaultpro.com → Tenant application stack
Platform Services: Shared APIs accessible by all tenants

Tenant Identification

Admin Tenant ID: "admin" (hardcoded identifier)
Regular Tenant IDs: Alphanumeric slugs (e.g., "acme-corp", "demo-tenant")
Auth0 Storage: tenant_id stored in user metadata
JWT Claims: Include tenant_id for downstream service authentication

Database Strategy

Platform Database: Shared tenant management + vehicle platform data
Per-Tenant Databases: Separate PostgreSQL container per tenant
Schema: Same application schema deployed to each tenant database
Migration: Big bang transformation (breaking changes acceptable)

Implementation Plan

Phase 1: Multi-Tenant Foundation & Platform Services

1.1 Create Tenant Management Platform Service

New Service: mvp-platform-tenants

Directory Structure:

mvp-platform-services/tenants/
├── api/
│   ├── main.py              # FastAPI application
│   ├── models/              # SQLAlchemy models
│   ├── routes/              # API endpoints
│   └── services/            # Business logic
├── sql/
│   └── schema/
│       ├── 001_tenants_schema.sql
│       └── 002_tenant_signups_schema.sql
├── docker/
│   └── Dockerfile.api
└── README.md

Database Schema (platform-postgres):

-- Tenant registry
CREATE TABLE tenants (
    id VARCHAR(100) PRIMARY KEY,              -- 'admin', 'acme-corp', etc.
    name VARCHAR(255) NOT NULL,               -- Display name
    subdomain VARCHAR(100) UNIQUE NOT NULL,   -- Same as id for simplicity  
    status VARCHAR(50) DEFAULT 'active',      -- active, pending, suspended
    admin_user_id VARCHAR(255),               -- Auth0 user ID of tenant admin
    settings JSONB DEFAULT '{}',              -- Tenant-specific configuration
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Tenant signup approval workflow
CREATE TABLE tenant_signups (
    id SERIAL PRIMARY KEY,
    tenant_id VARCHAR(100) REFERENCES tenants(id),
    user_email VARCHAR(255) NOT NULL,
    user_auth0_id VARCHAR(255),               -- Auth0 user ID after signup
    status VARCHAR(50) DEFAULT 'pending',     -- pending, approved, rejected
    requested_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    approved_by VARCHAR(255),                 -- Auth0 ID of approving admin
    approved_at TIMESTAMP
);

-- Initial data
INSERT INTO tenants (id, name, subdomain, status, admin_user_id) 
VALUES ('admin', 'Admin Tenant', 'admin', 'active', NULL);

API Endpoints (/api/v1/tenants):

POST   /tenants                    # Create new tenant (platform admin only)
GET    /tenants                    # List all tenants (platform admin only)  
GET    /tenants/{tenant_id}        # Get tenant details
PUT    /tenants/{tenant_id}        # Update tenant settings
DELETE /tenants/{tenant_id}        # Suspend tenant

POST   /tenants/{tenant_id}/signups    # Request signup approval
GET    /tenants/{tenant_id}/signups    # List pending signups (tenant admin only)
PUT    /signups/{signup_id}/approve    # Approve signup (tenant admin only)
PUT    /signups/{signup_id}/reject     # Reject signup (tenant admin only)

1.2 Create Landing Page Platform Service

New Service: mvp-platform-landing

Directory Structure:

mvp-platform-services/landing/
├── src/
│   ├── App.tsx
│   ├── components/
│   │   ├── HomePage.tsx
│   │   ├── TenantSignup.tsx
│   │   └── TenantLogin.tsx
│   ├── services/
│   │   ├── auth0.ts
│   │   └── tenantService.ts
│   └── utils/
│       └── routing.ts
├── public/
├── package.json
├── Dockerfile
└── README.md

Key Features:

Homepage: Marketing content at motovaultpro.com
Tenant Signup: Forms at motovaultpro.com/signup/{tenant-id}
Auth0 Integration: Tenant-aware authentication flow
Routing Logic: Redirect authenticated users to their tenant subdomain

Signup Flow:

User visits motovaultpro.com/signup/{tenant-id}
Landing page validates tenant exists and accepts signups
Auth0 signup with tenant_id stored in user metadata
User status set to "pending" until admin approval
Entry created in tenant_signups table
Tenant admin receives notification to approve/reject

1.3 Update Docker Compose for Multi-Tenant Architecture

New docker-compose.yml Structure:

version: '3.8'

services:
  # Platform Services (Shared)
  mvp-platform-tenants:
    build: ./mvp-platform-services/tenants/docker/Dockerfile.api
    environment:
      - DATABASE_URL=postgresql://platform_user:${PLATFORM_DB_PASSWORD}@platform-postgres:5432/platform
    depends_on:
      - platform-postgres
    ports:
      - "8001:8000"

  mvp-platform-landing:
    build: ./mvp-platform-services/landing
    environment:
      - REACT_APP_AUTH0_DOMAIN=${AUTH0_DOMAIN}
      - REACT_APP_TENANTS_API_URL=http://mvp-platform-tenants:8000
    ports:
      - "3002:3000"

  mvp-platform-vehicles-api:
    # Existing service - no changes needed
    
  platform-postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: platform
      POSTGRES_USER: platform_user
      POSTGRES_PASSWORD: ${PLATFORM_DB_PASSWORD}
    volumes:
      - ./mvp-platform-services/tenants/sql/schema:/docker-entrypoint-initdb.d
      - platform_postgres_data:/var/lib/postgresql/data
    ports:
      - "5434:5432"

  platform-redis:
    image: redis:7-alpine
    ports:
      - "6381:6379"

  # Admin Tenant (Current Implementation Renamed)
  admin-backend:
    build: ./backend
    environment:
      - TENANT_ID=admin
      - DB_HOST=admin-postgres
      - REDIS_URL=redis://admin-redis:6379
      - PLATFORM_TENANTS_API_URL=http://mvp-platform-tenants:8000
    depends_on:
      - admin-postgres
      - admin-redis

  admin-frontend:
    build: ./frontend
    environment:
      - REACT_APP_API_BASE_URL=http://admin-backend:3001
      - REACT_APP_TENANT_ID=admin
    depends_on:
      - admin-backend

  admin-postgres:
    # Existing postgres service renamed
    
  admin-redis:
    # Existing redis service renamed

volumes:
  platform_postgres_data:
  # Keep existing volumes, add tenant-specific volumes as needed

Phase 2: Authentication & Tenant-Aware Auth0

2.1 Multi-Tenant Auth0 Configuration

Auth0 Application Settings:

Allowed Callback URLs:
- http://localhost:3002/callback (landing page development)
- https://motovaultpro.com/callback (landing page production)
- http://admin.motovaultpro.local/callback (admin tenant development)
- https://admin.motovaultpro.com/callback (admin tenant production)
- http://{tenant-id}.motovaultpro.local/callback (tenant development)
- https://{tenant-id}.motovaultpro.com/callback (tenant production)

Auth0 Rules for Tenant Context:

function addTenantToToken(user, context, callback) {
  const namespace = 'https://motovaultpro.com/';
  
  // Extract tenant from signup metadata or determine from email domain
  let tenantId = user.user_metadata && user.user_metadata.tenant_id;
  
  // For existing users, default to admin tenant
  if (!tenantId) {
    tenantId = 'admin';
  }
  
  // Add tenant_id to JWT token
  context.idToken[namespace + 'tenant_id'] = tenantId;
  context.accessToken[namespace + 'tenant_id'] = tenantId;
  
  callback(null, user, context);
}

User Metadata Schema:

{
  "user_metadata": {
    "tenant_id": "admin",
    "signup_status": "approved",
    "approval_date": "2024-01-01T00:00:00Z"
  }
}

2.2 Landing Page Auth0 Integration

Tenant-Specific Signup (src/components/TenantSignup.tsx):

interface TenantSignupProps {
  tenantId: string;
}

export const TenantSignup: React.FC<TenantSignupProps> = ({ tenantId }) => {
  const { loginWithRedirect } = useAuth0();

  const handleSignup = async () => {
    await loginWithRedirect({
      screen_hint: 'signup',
      redirectUri: `${window.location.origin}/callback`,
      // Store tenant_id in Auth0 user metadata during signup
      signup: {
        user_metadata: {
          tenant_id: tenantId,
          signup_status: 'pending'
        }
      }
    });
  };

  return (
    <div>
      <h2>Sign up for {tenantId}</h2>
      <button onClick={handleSignup}>
        Create Account
      </button>
    </div>
  );
};

Post-Authentication Routing (src/utils/routing.ts):

export const redirectToTenant = (user: Auth0User) => {
  const tenantId = user['https://motovaultpro.com/tenant_id'];
  const status = user.user_metadata?.signup_status;
  
  if (status === 'pending') {
    // Show "approval pending" message
    window.location.href = '/approval-pending';
    return;
  }
  
  if (status !== 'approved') {
    // Invalid user state
    window.location.href = '/access-denied';
    return;
  }
  
  // Redirect to tenant subdomain
  const subdomain = tenantId === 'admin' ? 'admin' : tenantId;
  window.location.href = `http://${subdomain}.motovaultpro.local`;
};

Admin Dashboard for Approval (in admin tenant):

// Add to admin frontend: src/features/tenant-management/
export const SignupApprovals: React.FC = () => {
  const [pendingSignups, setPendingSignups] = useState([]);
  
  const approveSignup = async (signupId: string) => {
    await fetch(`/api/tenants/signups/${signupId}/approve`, {
      method: 'PUT',
      headers: { Authorization: `Bearer ${token}` }
    });
    // Update Auth0 user metadata to approved
    // Refresh list
  };
  
  return (
    <div>
      <h2>Pending Signups</h2>
      {pendingSignups.map(signup => (
        <div key={signup.id}>
          <p>{signup.user_email} wants to join {signup.tenant_id}</p>
          <button onClick={() => approveSignup(signup.id)}>
            Approve
          </button>
        </div>
      ))}
    </div>
  );
};

Phase 3: Application Stack Tenant Transformation

3.1 Add Tenant Context Throughout Backend

Tenant Detection Middleware (backend/src/core/middleware/tenant.ts):

import { FastifyRequest, FastifyReply, HookHandlerDoneFunction } from 'fastify';

export interface TenantRequest extends FastifyRequest {
  tenantId: string;
}

export const tenantMiddleware = (
  request: TenantRequest,
  reply: FastifyReply,
  done: HookHandlerDoneFunction
) => {
  // Method 1: From environment variable (container-level)
  const envTenantId = process.env.TENANT_ID;
  
  // Method 2: From JWT token claims
  const jwtTenantId = request.user?.['https://motovaultpro.com/tenant_id'];
  
  // Method 3: From subdomain parsing (if needed)
  const host = request.headers.host || '';
  const subdomain = host.split('.')[0];
  
  // Priority: Environment > JWT > Subdomain
  request.tenantId = envTenantId || jwtTenantId || subdomain || 'admin';
  
  // Validate tenant exists
  if (!isValidTenant(request.tenantId)) {
    reply.code(403).send({ error: 'Invalid tenant' });
    return;
  }
  
  done();
};

const isValidTenant = (tenantId: string): boolean => {
  // Query platform tenants service to validate
  // For now, hardcode known tenants
  return ['admin', 'demo-tenant', 'acme-corp'].includes(tenantId);
};

Environment-Based Tenant Configuration:

// backend/src/core/config/tenant.ts
export const getTenantConfig = () => {
  const tenantId = process.env.TENANT_ID || 'admin';
  
  return {
    tenantId,
    databaseUrl: process.env.DATABASE_URL || `postgresql://user:pass@${tenantId}-postgres:5432/${tenantId}`,
    redisUrl: process.env.REDIS_URL || `redis://${tenantId}-redis:6379`,
    platformServicesUrl: process.env.PLATFORM_SERVICES_URL || 'http://mvp-platform-tenants:8000',
    isAdminTenant: tenantId === 'admin'
  };
};

Update Database Configuration (backend/src/core/config/database.ts):

import { Pool } from 'pg';
import { getTenantConfig } from './tenant';

const tenantConfig = getTenantConfig();

export const pool = new Pool({
  connectionString: tenantConfig.databaseUrl,
  // Connection pool per tenant database
});

// Update all queries to use tenant-specific database
// No changes needed to query logic since each tenant has separate DB

3.2 Convert Current Implementation to Admin Tenant

Step 1: Rename Existing Containers

# In docker-compose.yml, rename:
backend -> admin-backend
frontend -> admin-frontend  
postgres -> admin-postgres
redis -> admin-redis
minio -> admin-minio

Step 2: Update Environment Variables

admin-backend:
  build: ./backend
  environment:
    - TENANT_ID=admin
    - DATABASE_URL=postgresql://motovault_user:${DB_PASSWORD}@admin-postgres:5432/motovault
    - REDIS_URL=redis://admin-redis:6379
    - PLATFORM_TENANTS_API_URL=http://mvp-platform-tenants:8000
    - PLATFORM_VEHICLES_API_URL=http://mvp-platform-vehicles-api:8000

admin-frontend:
  build: ./frontend
  environment:
    - REACT_APP_API_BASE_URL=http://admin-backend:3001
    - REACT_APP_TENANT_ID=admin
    - REACT_APP_AUTH0_DOMAIN=${AUTH0_DOMAIN}

Step 3: Add Admin-Only Features (backend/src/features/tenant-management/):

// New feature capsule for tenant management (admin only)
export const tenantManagementRoutes = async (fastify: FastifyInstance) => {
  // Middleware to ensure admin tenant only
  fastify.addHook('preHandler', async (request: TenantRequest, reply) => {
    if (request.tenantId !== 'admin') {
      reply.code(403).send({ error: 'Admin access required' });
      return;
    }
  });
  
  fastify.get('/api/admin/tenants', async (request, reply) => {
    // List all tenants
  });
  
  fastify.post('/api/admin/tenants', async (request, reply) => {
    // Create new tenant + provision infrastructure
  });
  
  fastify.get('/api/admin/signups', async (request, reply) => {
    // List pending signups across all tenants
  });
};

3.3 Per-Tenant Database Architecture

Tenant Provisioning Script (scripts/provision-tenant.sh):

#!/bin/bash
TENANT_ID=$1

if [ -z "$TENANT_ID" ]; then
  echo "Usage: $0 <tenant-id>"
  exit 1
fi

# Add tenant containers to docker-compose.yml
echo "
  ${TENANT_ID}-backend:
    build: ./backend
    environment:
      - TENANT_ID=${TENANT_ID}
      - DATABASE_URL=postgresql://motovault_user:\${DB_PASSWORD}@${TENANT_ID}-postgres:5432/motovault
      - REDIS_URL=redis://${TENANT_ID}-redis:6379
    depends_on:
      - ${TENANT_ID}-postgres
      - ${TENANT_ID}-redis

  ${TENANT_ID}-frontend:
    build: ./frontend
    environment:
      - REACT_APP_API_BASE_URL=http://${TENANT_ID}-backend:3001
      - REACT_APP_TENANT_ID=${TENANT_ID}
    depends_on:
      - ${TENANT_ID}-backend

  ${TENANT_ID}-postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: motovault
      POSTGRES_USER: motovault_user
      POSTGRES_PASSWORD: \${DB_PASSWORD}
    volumes:
      - ./backend/src/_system/migrations:/docker-entrypoint-initdb.d
      - ${TENANT_ID}_postgres_data:/var/lib/postgresql/data

  ${TENANT_ID}-redis:
    image: redis:7-alpine
    volumes:
      - ${TENANT_ID}_redis_data:/data
" >> docker-compose.yml

# Add volumes
echo "
  ${TENANT_ID}_postgres_data:
  ${TENANT_ID}_redis_data:
" >> docker-compose.yml

echo "Tenant ${TENANT_ID} provisioned. Run 'docker compose up -d' to start."

Automated Migration Deployment:

// backend/src/_system/migrations/run-all.ts - no changes needed
// Each tenant database gets the same schema deployed via init scripts
// Migrations run independently per tenant database

Phase 4: Platform Services Multi-Tenant Support

4.1 Update Platform Vehicles Service

Add Tenant Context (mvp-platform-services/vehicles/api/main.py):

from fastapi import Header, HTTPException

async def get_tenant_context(
    authorization: str = Header(),
    x_tenant_id: str = Header(None)
):
    # Extract tenant from JWT or header
    tenant_id = x_tenant_id or extract_tenant_from_jwt(authorization)
    
    if not tenant_id:
        raise HTTPException(status_code=403, detail="Tenant context required")
    
    return {
        "tenant_id": tenant_id,
        "is_admin": tenant_id == "admin"
    }

@app.get("/api/v1/vehicles/makes")
async def get_makes(
    year: int,
    tenant_context: dict = Depends(get_tenant_context)
):
    # Admin tenant gets all data, regular tenants get standard data
    # For vehicle platform data, this is mostly the same
    # But we can add tenant-specific caching or filtering if needed
    
    cache_key = f"makes:{year}:{tenant_context['tenant_id']}"
    # ... rest of endpoint logic

Service-to-Service Authentication:

// backend/src/features/vehicles/external/platform-vehicles/platform-vehicles.client.ts
export class PlatformVehiclesClient {
  constructor(
    private readonly baseUrl: string,
    private readonly apiKey: string,
    private readonly tenantId: string
  ) {}
  
  async getVehicleMakes(year: number) {
    const response = await axios.get(`${this.baseUrl}/api/v1/vehicles/makes`, {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'X-Tenant-ID': this.tenantId
      },
      params: { year }
    });
    
    return response.data;
  }
}

4.2 Tenant Management APIs

Platform Tenants Service Routes (mvp-platform-services/tenants/api/routes/tenants.py):

@router.post("/tenants")
async def create_tenant(
    tenant_data: TenantCreate,
    current_user: dict = Depends(get_admin_user)
):
    # Create tenant record
    tenant = await tenant_service.create_tenant(tenant_data)
    
    # Provision infrastructure (Docker containers)
    await provisioning_service.provision_tenant(tenant.id)
    
    return tenant

@router.get("/tenants/{tenant_id}/signups")
async def get_tenant_signups(
    tenant_id: str,
    current_user: dict = Depends(get_tenant_admin)
):
    # List pending signups for this tenant
    return await signup_service.get_pending_signups(tenant_id)

@router.put("/signups/{signup_id}/approve")
async def approve_signup(
    signup_id: int,
    current_user: dict = Depends(get_tenant_admin)
):
    # Approve signup and update Auth0 user metadata
    await signup_service.approve_signup(signup_id, current_user['sub'])
    await auth0_service.update_user_metadata(signup_id, {"signup_status": "approved"})
    
    return {"status": "approved"}

Phase 5: Docker Compose Multi-Tenant Deployment

5.1 Complete Multi-Tenant Docker Compose

Production-Ready docker-compose.yml:

version: '3.8'

services:
  # Reverse Proxy for Subdomain Routing
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./certs:/etc/nginx/certs
    depends_on:
      - mvp-platform-landing
      - admin-frontend

  # Platform Services (Shared Infrastructure)
  mvp-platform-landing:
    build: ./mvp-platform-services/landing
    environment:
      - REACT_APP_AUTH0_DOMAIN=${AUTH0_DOMAIN}
      - REACT_APP_AUTH0_CLIENT_ID=${AUTH0_CLIENT_ID}
      - REACT_APP_TENANTS_API_URL=http://mvp-platform-tenants:8000
    expose:
      - "3000"

  mvp-platform-tenants:
    build: ./mvp-platform-services/tenants/docker/Dockerfile.api
    environment:
      - DATABASE_URL=postgresql://platform_user:${PLATFORM_DB_PASSWORD}@platform-postgres:5432/platform
      - AUTH0_DOMAIN=${AUTH0_DOMAIN}
      - AUTH0_AUDIENCE=${AUTH0_AUDIENCE}
    depends_on:
      - platform-postgres
      - platform-redis
    expose:
      - "8000"

  mvp-platform-vehicles-api:
    build: ./mvp-platform-services/vehicles/docker/Dockerfile.api
    environment:
      - DATABASE_URL=postgresql://vehicles_user:${PLATFORM_DB_PASSWORD}@mvp-platform-vehicles-db:5432/vehicles
      - REDIS_URL=redis://platform-redis:6379
      - API_KEY=${PLATFORM_VEHICLES_API_KEY}
    expose:
      - "8000"

  # Platform Databases
  platform-postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: platform
      POSTGRES_USER: platform_user
      POSTGRES_PASSWORD: ${PLATFORM_DB_PASSWORD}
    volumes:
      - ./mvp-platform-services/tenants/sql/schema:/docker-entrypoint-initdb.d
      - platform_postgres_data:/var/lib/postgresql/data
    expose:
      - "5432"

  mvp-platform-vehicles-db:
    image: postgres:15
    environment:
      POSTGRES_DB: vehicles
      POSTGRES_USER: vehicles_user
      POSTGRES_PASSWORD: ${PLATFORM_DB_PASSWORD}
    volumes:
      - ./mvp-platform-services/vehicles/sql/schema:/docker-entrypoint-initdb.d
      - platform_vehicles_data:/var/lib/postgresql/data
    expose:
      - "5432"

  platform-redis:
    image: redis:7-alpine
    volumes:
      - platform_redis_data:/data
    expose:
      - "6379"

  # Admin Tenant (Converted Current Implementation)
  admin-backend:
    build: ./backend
    environment:
      - TENANT_ID=admin
      - DATABASE_URL=postgresql://motovault_user:${DB_PASSWORD}@admin-postgres:5432/motovault
      - REDIS_URL=redis://admin-redis:6379
      - PLATFORM_TENANTS_API_URL=http://mvp-platform-tenants:8000
      - PLATFORM_VEHICLES_API_URL=http://mvp-platform-vehicles-api:8000
      - PLATFORM_VEHICLES_API_KEY=${PLATFORM_VEHICLES_API_KEY}
      - AUTH0_DOMAIN=${AUTH0_DOMAIN}
      - AUTH0_AUDIENCE=${AUTH0_AUDIENCE}
    depends_on:
      - admin-postgres
      - admin-redis
      - mvp-platform-tenants
      - mvp-platform-vehicles-api
    expose:
      - "3001"

  admin-frontend:
    build: ./frontend
    environment:
      - REACT_APP_API_BASE_URL=http://admin-backend:3001
      - REACT_APP_TENANT_ID=admin
      - REACT_APP_AUTH0_DOMAIN=${AUTH0_DOMAIN}
      - REACT_APP_AUTH0_CLIENT_ID=${AUTH0_CLIENT_ID}
      - REACT_APP_AUTH0_AUDIENCE=${AUTH0_AUDIENCE}
    depends_on:
      - admin-backend
    expose:
      - "3000"

  admin-postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: motovault
      POSTGRES_USER: motovault_user
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - ./backend/src/_system/migrations:/docker-entrypoint-initdb.d
      - admin_postgres_data:/var/lib/postgresql/data
    expose:
      - "5432"

  admin-redis:
    image: redis:7-alpine
    volumes:
      - admin_redis_data:/data
    expose:
      - "6379"

  admin-minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    volumes:
      - admin_minio_data:/data
    expose:
      - "9000"
      - "9001"

volumes:
  # Platform volumes
  platform_postgres_data:
  platform_vehicles_data:
  platform_redis_data:
  
  # Admin tenant volumes
  admin_postgres_data:
  admin_redis_data:
  admin_minio_data:
  
  # Additional tenant volumes will be added via provisioning script

networks:
  default:
    name: motovaultpro_network

5.2 Nginx Configuration for Subdomain Routing

nginx.conf:

events {
    worker_connections 1024;
}

http {
    upstream landing {
        server mvp-platform-landing:3000;
    }
    
    upstream admin_frontend {
        server admin-frontend:3000;
    }
    
    # Main domain - Landing page
    server {
        listen 80;
        server_name motovaultpro.local motovaultpro.com;
        
        location / {
            proxy_pass http://landing;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }
    
    # Admin tenant
    server {
        listen 80;
        server_name admin.motovaultpro.local admin.motovaultpro.com;
        
        location / {
            proxy_pass http://admin_frontend;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
        
        location /api/ {
            proxy_pass http://admin-backend:3001;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }
    
    # Template for additional tenants (to be added via provisioning)
    # server {
    #     listen 80;
    #     server_name {tenant-id}.motovaultpro.local {tenant-id}.motovaultpro.com;
    #     
    #     location / {
    #         proxy_pass http://{tenant-id}-frontend:3000;
    #         proxy_set_header Host $host;
    #         proxy_set_header X-Real-IP $remote_addr;
    #     }
    #     
    #     location /api/ {
    #         proxy_pass http://{tenant-id}-backend:3001;
    #         proxy_set_header Host $host;
    #         proxy_set_header X-Real-IP $remote_addr;
    #     }
    # }
}

5.3 Local Development Setup

Update /etc/hosts for Local Development:

127.0.0.1 motovaultpro.local
127.0.0.1 admin.motovaultpro.local
127.0.0.1 demo-tenant.motovaultpro.local
127.0.0.1 acme-corp.motovaultpro.local

Development Commands:

# Start platform services only
docker compose up -d mvp-platform-landing mvp-platform-tenants mvp-platform-vehicles-api platform-postgres platform-redis

# Start admin tenant
docker compose up -d admin-backend admin-frontend admin-postgres admin-redis

# Provision new tenant
./scripts/provision-tenant.sh demo-tenant
docker compose up -d demo-tenant-backend demo-tenant-frontend demo-tenant-postgres demo-tenant-redis

# Update nginx config and restart
./scripts/update-nginx-for-tenant.sh demo-tenant
docker compose restart nginx

Testing & Validation

End-to-End Testing Scenarios

Landing Page:
- Visit http://motovaultpro.local → See homepage
- Click "Sign Up" → Redirect to tenant selection or Auth0
Admin Tenant:
- Visit http://admin.motovaultpro.local → Redirect to Auth0
- Login with admin user → Access admin tenant with full features
- Admin dashboard shows tenant management options
Regular Tenant:
- Visit http://demo-tenant.motovaultpro.local → Redirect to Auth0
- Login with tenant user → Access tenant-specific application
- No access to admin features
Signup Workflow:
- Visit http://motovaultpro.local/signup/demo-tenant → Tenant signup form
- Complete Auth0 signup → User status = "pending"
- Admin approves in admin dashboard → User status = "approved"
- User can now login to tenant subdomain

Database Validation

-- Platform database
SELECT * FROM tenants;
SELECT * FROM tenant_signups WHERE status = 'pending';

-- Admin tenant database (same as current)
SELECT COUNT(*) FROM vehicles;
SELECT COUNT(*) FROM fuel_logs;

-- Regular tenant database (isolated)
SELECT COUNT(*) FROM vehicles; -- Should be different from admin

Migration Checklist

Pre-Migration Backup

Export current database: pg_dump motovault > backup_pre_migration.sql
Backup configuration files and environment variables
Document current user accounts and Auth0 configuration

Phase 1 Implementation

Create mvp-platform-tenants service with database schema
Create mvp-platform-landing service with homepage and signup forms
Update docker-compose.yml with platform services
Test platform services independently

Phase 2 Implementation ✅ COMPLETED

Configure Auth0 for multi-tenant signup with metadata
Implement tenant-aware JWT tokens and rules
Build signup approval workflow in platform tenants service
Test Auth0 signup flow with tenant metadata

Phase 3 Implementation

Add tenant middleware to backend application
Rename existing containers to admin-* prefix
Update environment variables for admin tenant
Test admin tenant functionality at admin.motovaultpro.local

Phase 4 Implementation

Update platform vehicles service for tenant context
Build tenant management UI in admin tenant
Implement tenant provisioning automation scripts
Test tenant provisioning end-to-end

Phase 5 Implementation

Configure nginx for subdomain routing
Set up complete multi-tenant Docker Compose
Test multiple tenants running simultaneously
Validate tenant isolation and admin features

Post-Migration Validation

All existing data accessible in admin tenant
Admin tenant has tenant management capabilities
New tenant can be provisioned and accessed via subdomain
Signup approval workflow functions correctly
Platform services work across all tenants

Operational Considerations

Monitoring & Logging

Per-Tenant Metrics: Separate monitoring for each tenant's usage and performance
Platform Health: Monitor shared platform services across all tenants
Tenant Isolation: Ensure logs and metrics don't leak between tenants

Backup & Disaster Recovery

Per-Tenant Backups: Each tenant database backed up independently
Platform Backup: Tenant management and platform services data
Recovery Testing: Validate ability to restore individual tenants

Scaling Considerations

Tenant Limits: Define maximum number of tenants per instance
Resource Quotas: CPU/memory limits per tenant
Database Scaling: Plan for database performance with many tenant databases

Security

Tenant Isolation: Verify no cross-tenant data access possible
Admin Access: Secure admin tenant from unauthorized access
Platform Services: Ensure proper authentication between services

Future Enhancements

Advanced Multi-Tenancy Features

Tenant-Specific Branding: Custom logos, colors, domains per tenant
Feature Flags: Enable/disable features per tenant or tenant tier
Usage Analytics: Per-tenant usage metrics and billing integration
Custom Integrations: Tenant-specific external API integrations

Operational Improvements

Self-Service Tenant Creation: Allow tenant admins to create their own tenants
Automated Scaling: Auto-scale tenant resources based on usage
Advanced Monitoring: Tenant health dashboards and alerting
Backup Automation: Scheduled backups and retention policies

Migration to Kubernetes

Namespace-Based Isolation: Each tenant in separate K8s namespace
Helm Charts: Templated tenant provisioning
Service Mesh: Advanced traffic management and security
Horizontal Scaling: Auto-scaling based on tenant load

This comprehensive plan provides the foundation for transforming MotoVaultPro into a production-ready multi-tenant SaaS platform while maintaining all existing functionality in the admin tenant.

Implementation Progress

Phase 1: Multi-Tenant Foundation & Platform Services ✅ COMPLETED

1.1 Create Tenant Management Platform Service ✅

Location: mvp-platform-services/tenants/
Database Schema: Created tenant registry with tenants and tenant_signups tables
FastAPI Service: Basic tenant CRUD operations and signup approval workflow
Docker Container: Built and running on port 8001
Health Check: ✅ Healthy (http://localhost:8001/health)
Tenant Validation: ✅ Working (admin tenant created and accessible)

1.2 Create Landing Page Platform Service ✅

Location: mvp-platform-services/landing/
React Components: Homepage, TenantSignup, CallbackHandler created
Auth0 Integration: Configured for tenant-aware authentication
TypeScript Issues: ✅ Fixed all compilation errors:
- ✅ Added Vite environment type definitions
- ✅ Fixed Auth0 provider configuration
- ✅ Resolved component type errors
Docker Container: ✅ Built and running on port 3002
Health Check: ✅ Serving HTML content (HTTP 200)

1.3 Update Docker Compose Multi-Tenant Architecture ✅

Platform Services: Added mvp-platform-tenants, mvp-platform-landing, platform-postgres, platform-redis
Admin Tenant: Renamed existing services to admin-* prefix (admin-backend, admin-frontend, admin-postgres, etc.)
Environment Variables: Added TENANT_ID=admin for admin services
Volumes: Updated volume naming for multi-tenant structure
Service Dependencies: Configured proper startup order and health checks

1.4 Test Platform Services ✅

Platform Database: ✅ Running and healthy (port 5434)
Platform Redis: ✅ Running and healthy (port 6381)
Tenant Management API: ✅ Running and healthy (port 8001)
Admin Tenant Validation: ✅ Admin tenant record created and accessible
Landing Page: ✅ Running and serving content (port 3002)
Platform Integration: ✅ All services communicating properly
Service Health: ✅ All health checks passing

Phase 2: Authentication & Tenant-Aware Auth0 ✅ COMPLETED

2.1 Multi-Tenant Auth0 Configuration ✅

Auth0 Configuration Guide: Created comprehensive setup documentation in mvp-platform-services/tenants/AUTH0-CONFIG.md
Callback URLs: Documented for all tenant subdomains (development and production)
JWT Token Format: Specified custom claims for tenant context
Auth0 Rules: Complete rule definitions for tenant metadata and signup status

2.2 JWT Authentication System ✅

JWT Validation: Implemented full Auth0 JWKS-based token validation
JWKS Caching: 1-hour cache system for Auth0 public keys
Development Fallback: Mock authentication system for testing
Tenant Context: Automatic extraction of tenant_id from JWT claims
Libraries Added: httpx==0.25.2 for HTTP requests, python-jose for JWT handling

Enhanced Tenant Service: Comprehensive signup management APIs
Public Signup Endpoint: /api/v1/tenants/{tenant_id}/signups for user registration
Admin Approval: PUT endpoints for approval/rejection with audit trails
Tenant Access Controls: Proper authorization for tenant-specific data
End-to-End Testing: ✅ Verified complete signup and approval flow

2.4 Authentication Testing ✅

Mock Token System: Working development authentication
Tenant-Specific Access: Fixed tenant ID parsing for multi-hyphenated names
Admin Access: ✅ Verified admin can access all tenant data
Tenant Isolation: ✅ Confirmed tenants can only access own signups
Production Ready: System ready for Auth0 integration with environment variables

Next Steps - Phase 3: Tenant Application Stack

Phase 3 Status (Current)

✅ Tenant detection middleware implemented and applied post-auth per route (priority: env TENANT_ID > JWT claim > subdomain).
✅ Tenant validation now calls Platform Tenants API dynamically (no hardcoded lists) with a small in-memory cache.
✅ Backend config is tenant-aware:
- Database pool uses tenant connection string.
- Redis client uses tenant Redis URL.
✅ Platform Vehicles client sends X-Tenant-ID header; constructed with container TENANT_ID.
✅ Admin-only tenant management routes added in admin tenant:
- GET/POST /api/admin/tenants proxy to Platform Tenants.
- GET /api/admin/tenants/:tenantId/signups proxy for pending signups.
- PUT /api/admin/signups/:signupId/{approve|reject} proxy for approvals.
✅ Docker Compose updated to parameterize TENANT_ID for admin services; clone compose per tenant and set TENANT_ID accordingly.
✅ Admin frontend Nginx proxy fixed to target admin-backend.

Known Health/Operational Notes

⚠️ admin-frontend healthcheck probes HTTP 3000 which redirects to HTTPS 3443. Healthcheck may report unhealthy despite service working. Consider probing https://localhost:3443 or allowing redirects.
⚠️ mvp-platform-tenants runs and serves requests but the compose healthcheck targets /health. Ensure the service exposes /health or update the healthcheck path.
✅ admin-backend, admin-postgres, admin-redis, Platform Vehicles API/DB/Redis are running and passing their checks; backend migrations complete at startup.

Pending (Phase 3)

Add /health endpoint in Platform Tenants service (or adjust compose healthcheck).
Adjust admin-frontend healthcheck to probe HTTPS.
Optional: Introduce caching layer for tenant validation with configurable TTL and background refresh.
Optional: Expose admin UI in frontend for tenants and signups (API endpoints are ready).

Architecture Status

Platform Infrastructure: ✅ Operational
Admin Tenant: ✅ Ready (existing functionality preserved)
Multi-Tenant Foundation: ✅ Complete
Landing Page: ✅ Functional; healthcheck needs adjustment (HTTP→HTTPS redirect)
Authentication Flow: ✅ Complete (JWT validation and tenant isolation)
Signup Approval System: ✅ API ready; admin backend routes proxy to tenants service

Key Achievements in Phase 1

Zero-Downtime Migration: Existing functionality preserved as admin tenant
Scalable Architecture: Platform services ready for multiple tenants
Database Isolation: Separate databases per tenant capability established
Service Independence: Platform services and tenant services properly separated
Health Monitoring: All services have proper health checks and monitoring

Key Achievements in Phase 2

Production-Ready Authentication: Full JWT validation with Auth0 JWKS integration
Tenant Isolation: Secure tenant-specific access controls and authorization
Signup Workflow: Complete tenant signup and admin approval system
Development/Production Flexibility: Seamless fallback between mock and real authentication
Comprehensive Documentation: Complete Auth0 setup guide for production deployment
End-to-End Testing: Verified multi-tenant authentication and authorization flow

38 KiB Raw Blame History