# fourtheorem/saas-multitenant-serverless architecture

> Architecture diagram of the GitHub repository fourtheorem/saas-multitenant-serverless, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fourtheorem/saas-multitenant-serverless
- Repository: https://github.com/fourtheorem/saas-multitenant-serverless

## Overview

##### Project Type & Purpose
- Clearly state that this project is an AWS serverless multi-tenant SaaS example.
- Purpose: to demonstrate how to securely isolate tenant data using AWS Lambda, API Gateway, DynamoDB, Cognito, and dynamic IAM policies.

##### Main Components
- Client/Front-end (external consumer or application client) – though not explicitly a "frontend" in the repo, this is the system’s entry point (e.g., web or mobile clients).
- API Gateway – the edge service that receives client requests and routes them.
- AWS Lambda (Main API) – represented by the function in src/api/index.mjs. It handles business logic and processes API requests.
- AWS Lambda (Custom Authorizer) – found as src/authorizer.mjs. This component verifies the incoming requests, enforcing tenant-specific access controls via dynamic IAM policies.
- DynamoDB – used for tenant data storage.
- Cognito – manages authentication, allowing users to log in and get proper tokens which include session tags for IAM-based tenant isolation.
- IAM policies – dynamic policies (though not a separate code file, the concept is critical to the architecture) that ensure each tenant accesses only their own data.

##### Out Relationships and Data Flow
- From API Gateway, branch two paths:
- One to the Custom Authorizer Lambda which validates and extracts tenant information, then returns policy decisions.
- One to the Main API Lambda function which processes the request.
- Main API Lambda accessing DynamoDB for data storage/retrieval.
- That dynamic IAM policies (session tags) are enforced as part of the authentication/authorization flow – these might be annotated beside the Custom Authorizer or IAM component.

##### Architectural Patterns and Design Principles
- Serverless Pattern – Illustrate how AWS API Gateway, Lambda functions, and managed services reduce server maintenance.
- Security & Multi-Tenancy – Emphasize the usage of dynamic IAM policies along with Cognito-based authentication to enforce strict tenant isolation.
- Separation of Concerns – Note that one Lambda function handles the core API logic while a dedicated Lambda handles authorization, demonstrating clear modular design.

##### Relevant Technologies and Tools
- Serverless Framework – Referenced by the serverless.yaml file, highlight its role in deploying and managing the AWS resources.
- Node.js – The runtime environment used in your Lambda functions.
- AWS services (Lambda, API Gateway, DynamoDB, Cognito, IAM) – Make sure each of these is clearly represented with their roles.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    Client["Client/Front-end"]:::client
    Cognito["Cognito (Authentication)"]:::authentication
    APIGW["API Gateway"]:::api
    LambdaAuth["Lambda (Authorizer)"]:::lambda
    LambdaAPI["Lambda (API)"]:::lambda
    DynamoDB["DynamoDB"]:::database
    DynIAM["Dynamic IAM Policies<br/>(Session Tagging)"]:::security
    Serverless["Serverless Framework<br/>(serverless.yaml)"]:::deploy

    %% Data Flow
    Client -->|"HTTP_requests_with_auth_tokens"| APIGW
    Client -->|"obtains_tokens"| Cognito
    Cognito -->|"sends_tokens"| APIGW
    APIGW -->|"calls_authentication"| LambdaAuth
    LambdaAuth -->|"returns_policy_decisions"| APIGW
    APIGW -->|"routes_request"| LambdaAPI
    LambdaAPI -->|"accesses"| DynamoDB
    LambdaAuth -->|"enforces"| DynIAM
    Serverless -->|"configures"| APIGW

    %% Legend (as annotations)
    subgraph "Legend"
      direction LR
      LegClient["Client/Front-end (Light Blue)"]:::client
      LegAuth["Authentication (Light Red)"]:::authentication
      LegAPIGW["API Gateway (Light Blue)"]:::api
      LegLambda["Lambda Functions (Lavender)"]:::lambda
      LegDB["DynamoDB (Light Blue)"]:::database
      LegSec["Security (Light Pink)"]:::security
      LegDeploy["Deployment (Light Green)"]:::deploy
    end

    %% Click Events
    click LambdaAPI "https://github.com/fourtheorem/saas-multitenant-serverless/blob/main/src/api/index.mjs"
    click LambdaAuth "https://github.com/fourtheorem/saas-multitenant-serverless/blob/main/src/authorizer.mjs"
    click APIGW "https://github.com/fourtheorem/saas-multitenant-serverless/blob/main/serverless.yaml"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef authentication fill:#FDD,stroke:#000,stroke-width:2px;
    classDef api fill:#DAE8FC,stroke:#000,stroke-width:2px;
    classDef lambda fill:#E1D5E7,stroke:#000,stroke-width:2px,shape:ellipse;
    classDef database fill:#C9DAF8,stroke:#000,stroke-width:2px,shape:cylinder;
    classDef security fill:#F8CECC,stroke:#000,stroke-width:2px;
    classDef deploy fill:#D5E8D4,stroke:#000,stroke-width:2px;
```
