# mac83s/saas-core architecture

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

- Interactive diagram: https://gitdiagram.com/mac83s/saas-core
- Repository: https://github.com/mac83s/saas-core

## Overview

SaaS Core is a modular Django and Next.js monolith for multiple product profiles, including a generic business product. The documented user-facing surface includes a panel, marketing pages, pricing, and public company sites; the tree also shows booking, commerce, billing, identity, and assistant capabilities. A representative public-content workflow is crawler or feed client → frontend projection route → backend public-site API. The graph retains major product modules, but several backend paths are unsampled; their connections are omitted unless visible in the excerpts, source index, or README.

Main entry points: [`apps/backend/src/saas_core/modules/core/organizations/models.py`](https://github.com/mac83s/saas-core/blob/main/apps/backend/src/saas_core/modules/core/organizations/models.py) (Organizations and tenancy), [`apps/backend/src/saas_core/modules/core/organizations/command_registry.py`](https://github.com/mac83s/saas-core/blob/main/apps/backend/src/saas_core/modules/core/organizations/command_registry.py) (Assistant commands), [`apps/backend/src/saas_core/modules/shared/booking`](https://github.com/mac83s/saas-core/tree/main/apps/backend/src/saas_core/modules/shared/booking) (Booking), [`apps/backend/src/saas_core/modules/shared/commerce/models.py`](https://github.com/mac83s/saas-core/blob/main/apps/backend/src/saas_core/modules/shared/commerce/models.py) (Orders and payments)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_panel["SaaS panel<br/>[page.tsx]"]
  node_marketing["Marketing and pricing<br/>[page.tsx]"]
end

subgraph group_tenancy["Tenancy and identity"]
  node_identity["Identity and sessions<br/>[models.py]"]
  node_organization[("Organizations and tenancy<br/>[models.py]")]
  node_settings["Organization settings"]
  node_commands["Assistant commands"]
end

subgraph group_business["Business modules"]
  node_booking["Booking"]
  node_customers["Customer records"]
  node_commerce[("Orders and payments<br/>[models.py]")]
  node_billing["Plans and entitlements"]
  node_assistant["Assistant"]
end

subgraph group_content["Public content"]
  node_site_admin["Site management"]
  node_site_blocks["Site block rendering<br/>[core-manifest.ts]"]
  node_public_routes["Public site routes<br/>[page.tsx]"]
  node_projection["Feed and media projection"]
  node_site_backend["Public Sites API"]
end

subgraph group_platform["Platform services"]
  node_database[("Application database")]
end

node_operator(("Company operator"))
node_visitor(("Site visitor"))
node_crawler(("Crawler or feed client"))

node_operator -->|"uses"| node_panel
node_operator -->|"views"| node_marketing
node_crawler -->|"requests feed"| node_projection
node_projection -->|"fetches public data"| node_site_backend
node_visitor -.->|"requests site"| node_public_routes
node_public_routes -.->|"renders blocks"| node_site_blocks
node_panel -.->|"authenticates"| node_identity
node_identity -.->|"joins tenant"| node_organization
node_organization -.->|"persists tenant data"| node_database
node_settings -.->|"resolves settings"| node_organization
node_commands -->|"builds settings commands"| node_settings
node_booking -->|"registers customer hooks"| node_customers
node_commerce -->|"registers customer hooks"| node_customers
node_billing -->|"registers plan limits"| node_organization
node_booking -.->|"registers commands"| node_commands
node_commerce -->|"registers commands"| node_commands
node_assistant -.->|"uses commands"| node_commands
node_site_admin -.->|"serves public content"| node_site_backend

click node_panel "https://github.com/mac83s/saas-core/blob/main/apps/frontend/src/app/%5Blocale%5D/panel/page.tsx"
click node_marketing "https://github.com/mac83s/saas-core/blob/main/apps/frontend/src/app/%5Blocale%5D/(marketing)/pricing/page.tsx"
click node_identity "https://github.com/mac83s/saas-core/blob/main/apps/backend/src/saas_core/modules/core/identity/models.py"
click node_organization "https://github.com/mac83s/saas-core/blob/main/apps/backend/src/saas_core/modules/core/organizations/models.py"
click node_settings "https://github.com/mac83s/saas-core/blob/main/apps/backend/src/saas_core/modules/core/organizations/settings_registry.py"
click node_commands "https://github.com/mac83s/saas-core/blob/main/apps/backend/src/saas_core/modules/core/organizations/command_registry.py"
click node_booking "https://github.com/mac83s/saas-core/tree/main/apps/backend/src/saas_core/modules/shared/booking"
click node_customers "https://github.com/mac83s/saas-core/tree/main/apps/backend/src/saas_core/modules/shared/customers"
click node_commerce "https://github.com/mac83s/saas-core/blob/main/apps/backend/src/saas_core/modules/shared/commerce/models.py"
click node_billing "https://github.com/mac83s/saas-core/tree/main/apps/backend/src/saas_core/modules/shared/billing"
click node_assistant "https://github.com/mac83s/saas-core/tree/main/apps/backend/src/saas_core/modules/shared/assistant"
click node_site_admin "https://github.com/mac83s/saas-core/tree/main/apps/backend/src/saas_core/modules/shared/sites"
click node_site_blocks "https://github.com/mac83s/saas-core/blob/main/packages/site-blocks/src/core-manifest.ts"
click node_public_routes "https://github.com/mac83s/saas-core/blob/main/apps/frontend/src/app/site-renderer/%5B%5B...path%5D%5D/page.tsx"
click node_projection "https://github.com/mac83s/saas-core/blob/main/apps/frontend/src/modules/shared/sites/public-projection.ts"
click node_site_backend "https://github.com/mac83s/saas-core/tree/main/apps/backend/src/saas_core/modules/shared/sites"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_panel,node_marketing,node_crawler toneBlue
class node_identity,node_organization,node_settings,node_commands toneAmber
class node_booking,node_customers,node_commerce,node_billing,node_assistant toneMint
class node_site_admin,node_site_blocks,node_public_routes,node_projection,node_site_backend toneRose
class node_database,node_operator,node_visitor toneIndigo
```

## Components

### User experience

- [SaaS panel](https://github.com/mac83s/saas-core/blob/main/apps/frontend/src/app/%5Blocale%5D/panel/page.tsx): `apps/frontend/src/app/[locale]/panel/page.tsx`
- [Marketing and pricing](https://github.com/mac83s/saas-core/blob/main/apps/frontend/src/app/%5Blocale%5D/(marketing)/pricing/page.tsx): `apps/frontend/src/app/[locale]/(marketing)/pricing/page.tsx`

### Tenancy and identity

- [Identity and sessions](https://github.com/mac83s/saas-core/blob/main/apps/backend/src/saas_core/modules/core/identity/models.py): `apps/backend/src/saas_core/modules/core/identity/models.py`
- [Organizations and tenancy](https://github.com/mac83s/saas-core/blob/main/apps/backend/src/saas_core/modules/core/organizations/models.py): `apps/backend/src/saas_core/modules/core/organizations/models.py`
- [Organization settings](https://github.com/mac83s/saas-core/blob/main/apps/backend/src/saas_core/modules/core/organizations/settings_registry.py): `apps/backend/src/saas_core/modules/core/organizations/settings_registry.py`
- [Assistant commands](https://github.com/mac83s/saas-core/blob/main/apps/backend/src/saas_core/modules/core/organizations/command_registry.py): `apps/backend/src/saas_core/modules/core/organizations/command_registry.py`

### Business modules

- [Booking](https://github.com/mac83s/saas-core/tree/main/apps/backend/src/saas_core/modules/shared/booking): `apps/backend/src/saas_core/modules/shared/booking`
- [Customer records](https://github.com/mac83s/saas-core/tree/main/apps/backend/src/saas_core/modules/shared/customers): `apps/backend/src/saas_core/modules/shared/customers`
- [Orders and payments](https://github.com/mac83s/saas-core/blob/main/apps/backend/src/saas_core/modules/shared/commerce/models.py): `apps/backend/src/saas_core/modules/shared/commerce/models.py`
- [Plans and entitlements](https://github.com/mac83s/saas-core/tree/main/apps/backend/src/saas_core/modules/shared/billing): `apps/backend/src/saas_core/modules/shared/billing`
- [Assistant](https://github.com/mac83s/saas-core/tree/main/apps/backend/src/saas_core/modules/shared/assistant): `apps/backend/src/saas_core/modules/shared/assistant`

### Public content

- [Site management](https://github.com/mac83s/saas-core/tree/main/apps/backend/src/saas_core/modules/shared/sites): `apps/backend/src/saas_core/modules/shared/sites`
- [Site block rendering](https://github.com/mac83s/saas-core/blob/main/packages/site-blocks/src/core-manifest.ts): `packages/site-blocks/src/core-manifest.ts`
- [Public site routes](https://github.com/mac83s/saas-core/blob/main/apps/frontend/src/app/site-renderer/%5B%5B...path%5D%5D/page.tsx): `apps/frontend/src/app/site-renderer/[[...path]]/page.tsx`
- [Feed and media projection](https://github.com/mac83s/saas-core/blob/main/apps/frontend/src/modules/shared/sites/public-projection.ts): `apps/frontend/src/modules/shared/sites/public-projection.ts`
- [Public Sites API](https://github.com/mac83s/saas-core/tree/main/apps/backend/src/saas_core/modules/shared/sites): `apps/backend/src/saas_core/modules/shared/sites`

### Platform services

- **Application database**

### Other components

- **Company operator**
- **Site visitor**
- **Crawler or feed client**

## Connections

- Company operator → SaaS panel: uses (evidence: `README.md`)
- Company operator → Marketing and pricing: views (evidence: `README.md`)
- Crawler or feed client → Feed and media projection: requests feed (evidence: `apps/frontend/src/modules/shared/sites/public-projection.ts`)
- Feed and media projection → Public Sites API: fetches public data (evidence: `apps/frontend/src/modules/shared/sites/public-projection.ts`)
- Site visitor → Public site routes: requests site
- Public site routes → Site block rendering: renders blocks
- SaaS panel → Identity and sessions: authenticates
- Identity and sessions → Organizations and tenancy: joins tenant
- Organizations and tenancy → Application database: persists tenant data
- Organization settings → Organizations and tenancy: resolves settings (evidence: `apps/backend/src/saas_core/modules/core/organizations/settings_registry.py`)
- Assistant commands → Organization settings: builds settings commands (evidence: `apps/backend/src/saas_core/modules/core/organizations/settings_commands.py`)
- Booking → Customer records: registers customer hooks (evidence: `apps/backend/src/saas_core/modules/shared/booking/apps.py`)
- Orders and payments → Customer records: registers customer hooks (evidence: `apps/backend/src/saas_core/modules/shared/commerce/apps.py`)
- Plans and entitlements → Organizations and tenancy: registers plan limits (evidence: `apps/backend/src/saas_core/modules/shared/billing/apps.py`)
- Booking → Assistant commands: registers commands
- Orders and payments → Assistant commands: registers commands
- Assistant → Assistant commands: uses commands
- Site management → Public Sites API: serves public content
