What This Template Covers
The SaaS system architecture template covers seven structural areas that together define how a production SaaS system is built and deployed. The component diagram section provides a structure for documenting the major system components and how they communicate. This includes the frontend layer, the API layer, background job processing, the data layer, external integrations, and the AI service layer if applicable. The component diagram is the map that new engineers use to understand the system and that the development team uses to reason about dependencies and failure modes. The data model patterns section covers the core data structures that most SaaS products share: user and organisation models for multi-tenancy, subscription and billing models, feature flag models, audit log models, and notification models. Getting these patterns right early prevents expensive refactoring later. The authentication and authorisation section covers the integration patterns for modern auth providers (Clerk, Auth0, Supabase Auth) and the role-based access control model that maps to the product's permission requirements. The billing integration section covers the Stripe data model and the webhook handling patterns that keep subscription state in sync between the payment provider and the product database. The AI service layer section covers the architecture for AI components: model provider integration, prompt management, caching strategy, and observability. The observability stack section covers logging, metrics, error tracking, and performance monitoring. The deployment topology section covers the hosting and infrastructure decisions that determine reliability, cost, and scalability.
How to Use This Template Step by Step
Step one: sketch the component diagram before any other section. List every major system component that will exist in production. Group them into layers: presentation layer (web app, mobile app, browser extension), API layer (REST or GraphQL API server, serverless functions), processing layer (background jobs, queues, event processors), data layer (primary database, cache, vector store, file storage), and external services (auth provider, payment provider, AI model provider, email provider, analytics). Step two: for each component, document the technology choice and the reason. Use a format that captures: component name, technology, why this technology was chosen (concisely), and any significant alternatives considered. The reasoning matters because it prevents future team members from re-litigating settled decisions without new information. Step three: design the multi-tenancy model. Most SaaS products are built on an organisation model where multiple users belong to one organisation and all data belongs to an organisation. Decide: will you use shared tables with tenant ID columns (most common, simplest), separate schemas per tenant (good for enterprise products with data isolation requirements), or separate databases per tenant (highest isolation, highest operational complexity). For products with GDPR implications, the data isolation model affects your data subject request handling. Step four: document the data models for users, organisations, subscriptions, and audit logs. These four models underpin most SaaS products. Get them right before building anything else. Common mistakes include: not linking subscriptions to organisations (causes problems when a user changes their email), not including soft-delete from the start (causes GDPR data management problems), and not designing audit logs before the first feature ships (audit events added retroactively are always incomplete). Step five: document the auth and billing integration patterns. For auth, specify: which provider, how sessions are managed, how the user record in your database relates to the auth provider record, and how role-based access control is implemented. For billing, specify: the Stripe objects you use (Customer, Subscription, Price, Product), the webhook events you handle, and how subscription state changes are reflected in feature access. Step six: define the AI service layer if applicable. Document: which model provider, how prompts are stored and versioned, what caching strategy reduces API costs, how errors from the AI provider are handled, and how AI usage is tracked for cost management. Step seven: define the observability stack. Specify the logging approach, the error tracking tool, the performance monitoring tool, and the alerting strategy. Document what a critical alert looks like and who is responsible for responding.
Section-by-Section Walkthrough
The component diagram section should produce a diagram (even a simple hand-drawn one) as well as a written description. The diagram communicates the system structure at a glance. The written description adds the details that a diagram cannot contain: the communication protocol between components (REST, GraphQL, message queue), the authentication mechanism for each connection, and the expected data volumes. The multi-tenancy data model section should include the SQL schema for the core tables: users, organisations, memberships (the many-to-many relationship between users and organisations), and subscriptions. Include foreign key relationships, index decisions, and soft-delete columns. If using PostgreSQL with row-level security, document the RLS policies that enforce tenant isolation. The authentication section should cover both the authentication flow (how a user logs in) and the session management approach (how the server validates that a request is from an authenticated user). For server-rendered applications and API-heavy applications, these have different designs. Document the token type (JWT or opaque token), its location (cookie or Authorization header), and its lifetime. The billing integration section is worth documenting in detail because Stripe's data model has subtleties that cause production bugs if not understood clearly. Document: the relationship between your organisation and a Stripe Customer, how multiple subscriptions are handled, what happens to feature access during the grace period after a failed payment, and how free trials are represented. The AI service layer section should cover the specific failure modes of AI API dependencies. Unlike database calls, AI API calls have variable latency, rate limits, and quality variability. The architecture should include: request timeout handling, retry logic with exponential backoff, fallback behaviour when the AI provider is unavailable, and cost monitoring with budget alerts. The observability section should define minimum viable observability for the MVP: application logs with structured fields (timestamp, request ID, user ID, organisation ID, action, outcome), error tracking with source mapping, and uptime monitoring. Enhanced observability (distributed tracing, custom metrics dashboards, AI output quality monitoring) can be added post-launch.
Common Mistakes This Template Prevents
The most common SaaS architecture mistake is not designing for multi-tenancy from the start. Adding tenant isolation to a single-tenant schema after data has been loaded is a painful migration. This template's explicit multi-tenancy section forces that decision before build starts. The second mistake is not including soft-delete from the start. Hard-deleting user or organisation records creates problems with referential integrity, audit trails, and GDPR right to erasure requests (which require being able to demonstrate that data has been deleted, which is harder if the deletion cascades in unexpected ways). A soft-delete pattern with a deleted_at timestamp column is the right default for SaaS data. The third mistake is under-specifying the billing integration. Stripe has a complex data model and webhook delivery is not guaranteed to be in order or exactly once. Systems that treat Stripe webhooks as reliable ordered events without idempotency handling create billing bugs that are very difficult to debug in production. The fourth mistake is building AI API integrations without error handling and fallback behaviour. AI APIs have higher failure rates than typical REST APIs, and their responses are less predictable. An architecture that treats an AI API call like a database query will fail visibly when the API rate-limits or returns an error.
Customisation Tips for Different Project Types
For AI-first SaaS products where the AI capability is the core product (not a supporting feature), the AI service layer section should be expanded significantly. Add sections for: prompt versioning strategy, model evaluation pipeline, caching layer design (semantic caching for repeated or similar queries), cost attribution (tracking AI costs per customer or per feature for pricing and margin analysis), and the human review workflow for AI outputs that require oversight. For B2B enterprise SaaS products with enterprise customers, the architecture needs to address single sign-on (SAML or OIDC integration), audit logging at the required depth for enterprise compliance (who did what, when, from which IP), and data residency requirements (UK or EU data storage for UK and EU enterprise customers, relevant under UK GDPR). For products in FCA-regulated financial services, the architecture needs to address record-keeping obligations under FCA SYSC rules, which may require immutable audit logs with extended retention periods. For products handling health data under NHS Digital frameworks, data residency, encryption standards, and access logging requirements are more stringent than standard commercial SaaS. For multi-region deployments, the architecture template should be extended to cover data sovereignty (which data can be processed in which region), latency optimisation (CDN and regional API routing), and disaster recovery across regions. Most MVPs do not need multi-region from day one, but the architecture should not make adding it prohibitively difficult.