# mooceanstudio/saas-starter-kit architecture

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

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

## Overview

This is a multi-tenant SaaS starter kit: a browser dashboard authenticates users, loads their organizations, and lets them manage tenant members, invitations, and projects through a FastAPI API. The backend enforces membership and role checks, applies business logic, and persists tenant-scoped data. The graph includes the documented capabilities whose implementation was not sampled, but omits uncertain wiring; for those areas, it uses only paths supported by the tree.

Main entry points: [`app/core/database.py`](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/core/database.py) (DB Session), [`app/api/auth.py`](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/api/auth.py) (Authentication Routes), [`app/api/deps.py`](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/api/deps.py) (Auth Dependencies), [`app/main.py`](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/main.py) (FastAPI App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_appjs["SPA Controller<br/>[app.js]"]
  node_apijs["API Client<br/>[api.js]"]
  node_ui["UI Helpers<br/>[ui.js]"]
end

subgraph group_api["HTTP API"]
  node_main["FastAPI App<br/>[main.py]"]
  node_authapi["Authentication Routes<br/>[auth.py]"]
  node_orgapi["Organization Routes<br/>[organizations.py]"]
  node_projectapi["Project Routes<br/>[projects.py]"]
  node_deps["Auth Dependencies<br/>[deps.py]"]
  node_schemas["API Schemas<br/>[schemas.py]"]
end

subgraph group_domain["Tenant Services"]
  node_security["JWT Security<br/>[security.py]"]
  node_usersvc["User Service<br/>[users.py]"]
  node_orgsvc["Organization Service<br/>[organizations.py]"]
  node_invitesvc["Invitation Service<br/>[invitations.py]"]
  node_projectsvc["Project Service<br/>[projects.py]"]
end

subgraph group_storage["Persistence"]
  node_entities["Tenant Models<br/>[entities.py]"]
  node_database["DB Session<br/>[database.py]"]
  node_store[("SQL Database")]
end

node_person(("User"))

node_person -->|"uses dashboard"| node_appjs
node_appjs -->|"calls API methods"| node_apijs
node_appjs -->|"renders with"| node_ui
node_apijs -->|"sends HTTP requests"| node_main
node_main -->|"mounts routes"| node_authapi
node_main -->|"mounts routes"| node_orgapi
node_main -->|"mounts routes"| node_projectapi
node_main -->|"creates schema"| node_database
node_authapi -->|"authenticates users"| node_usersvc
node_authapi -->|"creates first tenant"| node_orgsvc
node_authapi -->|"issues JWT"| node_security
node_authapi -->|"resolves current user"| node_deps
node_orgapi -->|"manages tenants"| node_orgsvc
node_orgapi -->|"manages invitations"| node_invitesvc
node_orgapi -->|"checks membership and role"| node_deps
node_projectapi -->|"manages projects"| node_projectsvc
node_projectapi -->|"checks membership and role"| node_deps
node_deps -->|"validates JWT"| node_security
node_deps -->|"loads user"| node_usersvc
node_deps -->|"resolves membership"| node_orgsvc
node_authapi -->|"validates and returns data"| node_schemas
node_orgapi -->|"validates and returns data"| node_schemas
node_projectapi -->|"validates and returns data"| node_schemas
node_usersvc -->|"queries and writes"| node_database
node_orgsvc -->|"queries and writes"| node_database
node_invitesvc -->|"queries and writes"| node_database
node_projectsvc -->|"queries and writes"| node_database
node_database -->|"maps ORM models"| node_entities
node_database -->|"reads and writes"| node_store

click node_appjs "https://github.com/mooceanstudio/saas-starter-kit/blob/main/frontend/js/app.js"
click node_apijs "https://github.com/mooceanstudio/saas-starter-kit/blob/main/frontend/js/api.js"
click node_ui "https://github.com/mooceanstudio/saas-starter-kit/blob/main/frontend/js/ui.js"
click node_main "https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/main.py"
click node_authapi "https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/api/auth.py"
click node_orgapi "https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/api/organizations.py"
click node_projectapi "https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/api/projects.py"
click node_deps "https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/api/deps.py"
click node_schemas "https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/schemas/schemas.py"
click node_security "https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/core/security.py"
click node_usersvc "https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/services/users.py"
click node_orgsvc "https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/services/organizations.py"
click node_invitesvc "https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/services/invitations.py"
click node_projectsvc "https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/services/projects.py"
click node_entities "https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/models/entities.py"
click node_database "https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/core/database.py"

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_appjs,node_apijs,node_ui,node_person toneBlue
class node_main,node_authapi,node_orgapi,node_projectapi,node_deps,node_schemas toneAmber
class node_security,node_usersvc,node_orgsvc,node_invitesvc,node_projectsvc toneMint
class node_entities,node_database,node_store toneRose
```

## Components

### Dashboard

- [SPA Controller](https://github.com/mooceanstudio/saas-starter-kit/blob/main/frontend/js/app.js): `frontend/js/app.js`
- [API Client](https://github.com/mooceanstudio/saas-starter-kit/blob/main/frontend/js/api.js): `frontend/js/api.js`
- [UI Helpers](https://github.com/mooceanstudio/saas-starter-kit/blob/main/frontend/js/ui.js): `frontend/js/ui.js`

### HTTP API

- [FastAPI App](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/main.py): `app/main.py`
- [Authentication Routes](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/api/auth.py): `app/api/auth.py`
- [Organization Routes](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/api/organizations.py): `app/api/organizations.py`
- [Project Routes](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/api/projects.py): `app/api/projects.py`
- [Auth Dependencies](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/api/deps.py): `app/api/deps.py`
- [API Schemas](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/schemas/schemas.py): `app/schemas/schemas.py`

### Tenant Services

- [JWT Security](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/core/security.py): `app/core/security.py`
- [User Service](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/services/users.py): `app/services/users.py`
- [Organization Service](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/services/organizations.py): `app/services/organizations.py`
- [Invitation Service](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/services/invitations.py): `app/services/invitations.py`
- [Project Service](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/services/projects.py): `app/services/projects.py`

### Persistence

- [Tenant Models](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/models/entities.py): `app/models/entities.py`
- [DB Session](https://github.com/mooceanstudio/saas-starter-kit/blob/main/app/core/database.py): `app/core/database.py`
- **SQL Database**

### Other components

- **User**

## Connections

- User → SPA Controller: uses dashboard
- SPA Controller → API Client: calls API methods
- SPA Controller → UI Helpers: renders with
- API Client → FastAPI App: sends HTTP requests
- FastAPI App → Authentication Routes: mounts routes
- FastAPI App → Organization Routes: mounts routes
- FastAPI App → Project Routes: mounts routes
- FastAPI App → DB Session: creates schema
- Authentication Routes → User Service: authenticates users
- Authentication Routes → Organization Service: creates first tenant
- Authentication Routes → JWT Security: issues JWT
- Authentication Routes → Auth Dependencies: resolves current user
- Organization Routes → Organization Service: manages tenants
- Organization Routes → Invitation Service: manages invitations
- Organization Routes → Auth Dependencies: checks membership and role
- Project Routes → Project Service: manages projects
- Project Routes → Auth Dependencies: checks membership and role
- Auth Dependencies → JWT Security: validates JWT
- Auth Dependencies → User Service: loads user
- Auth Dependencies → Organization Service: resolves membership
- Authentication Routes → API Schemas: validates and returns data
- Organization Routes → API Schemas: validates and returns data
- Project Routes → API Schemas: validates and returns data
- User Service → DB Session: queries and writes
- Organization Service → DB Session: queries and writes
- Invitation Service → DB Session: queries and writes
- Project Service → DB Session: queries and writes
- DB Session → Tenant Models: maps ORM models
- DB Session → SQL Database: reads and writes