01. SaaS Architecture

Chapter 1 of 24 · 15 min

KEY INSIGHT

SaaS architecture separates concerns into frontend clients, API services, and data stores, with authentication and billing as core cross-cutting concerns. A software-as-a-service product serving multiple customers requires a deliberate architectural approach. Unlike single-tenant applications where resources can be statically allocated, AI-powered SaaS must handle variable demand, usage-based billing, and strict data isolation across tenants. The foundational architecture consists of three layers. The presentation layer handles user interfaces—dashboards, API key management UIs, and usage visualization. These communicate with the service layer via REST or GraphQL APIs. The service layer contains the core business logic: AI model routing, token counting, rate limiting, and subscription management. The data layer stores everything from tenant records to individual API call logs. ```python # Typical SaaS request flow from fastapi import FastAPI, Request, Depends from sqlalchemy.orm import Session app = FastAPI() @app.middleware("http") async def tenant_middleware(request: Request, call_next): # Extract tenant from subdomain or header tenant_id = request.headers.get("X-Tenant-ID") if not tenant_id: tenant_id = extract_subdomain(request.url) request.state.tenant_id = tenant_id response = await call_next(request) response.headers["X-Tenant-ID"] = tenant_id return response ``` One common failure: hardcoding tenant identification logic. When tenant resolution is scattered across multiple files, debugging billing disputes becomes painful. Centralize tenant context in middleware and inject it into route handlers via dependency injection. The API gateway pattern works well here. Instead of each microservice handling authentication, a gateway layer validates API keys, identifies the tenant, and attaches tenant context to downstream requests. This reduces repeated auth logic and provides a single point for rate limiting. ```python # Gateway context propagation from contextvars import ContextVar tenant_context: ContextVar[str] = ContextVar("tenant_id") def get_current_tenant() -> str: return tenant_context.get() @app.get("/api/v1/models") async def list_models(tenant_id: str = Depends(get_tenant_from_header)): tenant_context.set(tenant_id) # All downstream calls inherit tenant context return model_service.list_available() ``` State management matters. Context variables prevent tenant leakage in async code but require discipline. Functions that don't receive tenant_id as a parameter should explicitly fetch it from context. Missing this step causes cross-tenant data access bugs that are difficult to reproduce in testing.

EXERCISE

Design the tenant resolution logic for a SaaS that supports both subdomain-based routing (tenant.example.com) and header-based identification. Document where each approach would fail and how you'd handle it.