# boxyhq/saas-starter-kit architecture

> Architecture diagram of the GitHub repository boxyhq/saas-starter-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/boxyhq/saas-starter-kit
- Repository: https://github.com/boxyhq/saas-starter-kit

## Overview

##### Main System Components

A. Frontend Layer
- Next.js Application (React Components)
- Authentication UI
- Team Management UI
- Account Management UI
- Billing Interface
- Webhook Management
- API Key Management

B. API Layer
- Authentication endpoints (/api/auth/*)
- Team Management endpoints (/api/teams/*)
- Webhook endpoints (/api/webhooks/*)
- SCIM endpoints (/api/scim/*)
- OAuth/SAML endpoints (/api/oauth/*)

C. Core Services Layer
- Authentication Service (NextAuth.js)
- SAML SSO Service (SAML Jackson)
- Directory Sync Service
- Webhook Orchestration (Svix)
- Audit Logging (Retraced)
- Payment Processing (Stripe)
- Email Service

D. Data Layer
- PostgreSQL Database
- Prisma ORM
- Session Management
- File Storage (for avatars)

##### Relationship Flows

- User authentication flows (traditional, SSO, magic link)
- Team management operations
- Webhook event propagation
- Directory synchronization
- Payment processing
- Audit log generation

##### External Service Integration

Integrations with:
- Stripe for payments
- Email service providers
- OAuth providers (Google, GitHub)
- SAML Identity Providers
- Svix for webhooks
- Retraced for audit logs

##### Implementation Details

Technical implementations:
- NextAuth.js configuration
- Prisma schema relationships
- API route structure
- Middleware placement
- Security headers
- Event handlers

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Frontend
        UI_Auth["Authentication UI"]
        UI_Team["Team Management UI"]
        UI_Account["Account Management UI"]
        UI_Billing["Billing Interface"]
        UI_Webhook["Webhook Management UI"]
        UI_APIKey["API Key Management UI"]
        UI_Shell["Frontend Shell"]
        UI_Common["Common Components"]
        UI_Email["Email Templates"]
    end

    subgraph API
        API_Auth["/api/auth"]
        API_Team["/api/teams"]
        API_Webhook["/api/webhooks"]
        API_SCIM["/api/scim"]
        API_OAuth["/api/oauth"]
    end

    subgraph CoreServices
        Auth["Authentication Service"]
        SAML["SAML SSO Service"]
        DSync["Directory Sync Service"]
        WebhookService["Webhook Orchestration"]
        AuditLog["Audit Logging"]
        Payment["Payment Processing"]
        Email["Email Service"]
        Session["Session Management"]
    end

    subgraph ExternalServices
        Stripe["Stripe"]
        EmailProvider["Email Provider"]
        OAuth["OAuth Providers"]
        SAML_IDP["SAML IdP"]
        Svix["Svix"]
        Retraced["Retraced"]
    end

    subgraph DataLayer
        DB[(PostgreSQL)]
        ORM["Prisma ORM"]
        Models["Data Models"]
    end

    %% Frontend to API
    UI_Auth --> API_Auth
    UI_Team --> API_Team
    UI_Webhook --> API_Webhook
    UI_APIKey --> API_OAuth
    UI_Account --> API_Auth

    %% API to Core Services
    API_Auth --> Auth
    API_OAuth --> SAML
    API_SCIM --> DSync
    API_Webhook --> WebhookService
    API_Team --> Session

    %% Core Services to External
    Payment --> Stripe
    Email --> EmailProvider
    Auth --> OAuth
    SAML --> SAML_IDP
    WebhookService --> Svix
    AuditLog --> Retraced

    %% Core Services to Data
    Auth --> ORM
    SAML --> ORM
    DSync --> ORM
    WebhookService --> ORM
    Session --> ORM
    ORM --> DB
    ORM --> Models

    %% Styling
    classDef frontend fill:#2196F3,color:white
    classDef api fill:#4CAF50,color:white
    classDef core fill:#FF9800,color:white
    classDef external fill:#9C27B0,color:white
    classDef data fill:#607D8B,color:white

    class UI_Auth,UI_Team,UI_Account,UI_Billing,UI_Webhook,UI_APIKey,UI_Shell,UI_Common,UI_Email frontend
    class API_Auth,API_Team,API_Webhook,API_SCIM,API_OAuth api
    class Auth,SAML,DSync,WebhookService,AuditLog,Payment,Email,Session core
    class Stripe,EmailProvider,OAuth,SAML_IDP,Svix,Retraced external
    class DB,ORM,Models data

    %% Click Events
    click UI_Auth "https://github.com/boxyhq/saas-starter-kit/tree/main/components/auth"
    click UI_Team "https://github.com/boxyhq/saas-starter-kit/tree/main/components/team"
    click UI_Account "https://github.com/boxyhq/saas-starter-kit/tree/main/components/account"
    click UI_Billing "https://github.com/boxyhq/saas-starter-kit/tree/main/components/billing"
    click UI_Webhook "https://github.com/boxyhq/saas-starter-kit/tree/main/components/webhook"
    click UI_APIKey "https://github.com/boxyhq/saas-starter-kit/tree/main/components/apiKey"
    click UI_Shell "https://github.com/boxyhq/saas-starter-kit/tree/main/components/shared/shell"
    click UI_Common "https://github.com/boxyhq/saas-starter-kit/tree/main/components/shared"
    click UI_Email "https://github.com/boxyhq/saas-starter-kit/tree/main/components/emailTemplates"
    
    click API_Auth "https://github.com/boxyhq/saas-starter-kit/tree/main/pages/api/auth"
    click API_Team "https://github.com/boxyhq/saas-starter-kit/tree/main/pages/api/teams"
    click API_Webhook "https://github.com/boxyhq/saas-starter-kit/tree/main/pages/api/webhooks"
    click API_SCIM "https://github.com/boxyhq/saas-starter-kit/tree/main/pages/api/scim"
    click API_OAuth "https://github.com/boxyhq/saas-starter-kit/tree/main/pages/api/oauth"
    
    click Auth "https://github.com/boxyhq/saas-starter-kit/blob/main/lib/auth.ts"
    click SAML "https://github.com/boxyhq/saas-starter-kit/tree/main/lib/jackson/sso"
    click DSync "https://github.com/boxyhq/saas-starter-kit/tree/main/lib/jackson/dsync"
    click WebhookService "https://github.com/boxyhq/saas-starter-kit/blob/main/lib/svix.ts"
    click AuditLog "https://github.com/boxyhq/saas-starter-kit/blob/main/lib/retraced.ts"
    click Payment "https://github.com/boxyhq/saas-starter-kit/blob/main/lib/stripe.ts"
    click Email "https://github.com/boxyhq/saas-starter-kit/tree/main/lib/email"
    click Session "https://github.com/boxyhq/saas-starter-kit/blob/main/lib/session.ts"
    
    click ORM "https://github.com/boxyhq/saas-starter-kit/blob/main/prisma/schema.prisma"
    click Models "https://github.com/boxyhq/saas-starter-kit/tree/main/models/*"
```
