# amanxchaubey/multi-tenant-saas architecture

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

- Interactive diagram: https://gitdiagram.com/amanxchaubey/multi-tenant-saas
- Repository: https://github.com/amanxchaubey/multi-tenant-saas

## Overview

Ledger is a multi-tenant B2B SaaS API. Its main workflow resolves an organization, authenticates a user, applies role checks, and serves organization, project, task, or billing operations; PostgreSQL RLS enforces tenant isolation. Authentication also covers organization selection, token renewal, email verification, and password recovery. The README documents Redis caching, optional RabbitMQ, Stripe billing, and Sentry; the sampled source does not show every service’s internal wiring.

Main entry points: [`src/app.js`](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/app.js) (Express API), [`src/modules/organizations/organization.routes.js`](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/organizations/organization.routes.js) (Organization routes), [`src/modules/auth/auth.service.js`](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/auth/auth.service.js) (Auth service), [`src/modules/billing/billing.controller.js`](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/billing/billing.controller.js) (Billing API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_app["Express API<br/>[app.js]"]
  node_tenant["Tenant resolver<br/>[tenant.js]"]
  node_authmw["Access auth<br/>[auth.js]"]
  node_authorize["Role checks<br/>[authorize.js]"]
end

subgraph group_identity["Identity"]
  node_auth_routes["Auth routes<br/>[auth.routes.js]"]
  node_auth_controller["Auth API<br/>[auth.controller.js]"]
  node_auth_service["Auth service<br/>[auth.service.js]"]
end

subgraph group_workspace["Workspace data"]
  node_org_routes["Organization routes"]
  node_org_controller["Organization API"]
  node_org_service["Organization service"]
  node_project_routes["Project routes<br/>[project.routes.js]"]
  node_project_controller["Project API"]
  node_project_service["Project service<br/>[project.service.js]"]
  node_task_routes["Task routes<br/>[task.routes.js]"]
  node_task_controller["Task API<br/>[task.controller.js]"]
  node_task_service["Task service<br/>[task.service.js]"]
  node_db_config["Database access<br/>[db.js]"]
  node_postgres[("PostgreSQL with RLS")]
  node_migrations["RLS schema"]
end

subgraph group_integrations["External services"]
  node_redis_config["Redis client<br/>[redis.js]"]
  node_redis[("Redis cache")]
  node_email["Email delivery<br/>[email.js]"]
  node_resend["Resend"]
  node_billing_controller["Billing API"]
  node_billing_service["Billing service<br/>[billing.service.js]"]
  node_stripe_config["Stripe client<br/>[stripe.js]"]
  node_stripe["Stripe"]
  node_sentry["Sentry reporting<br/>[sentry.js]"]
  node_rabbit_config["RabbitMQ client<br/>[rabbitmq.js]"]
  node_rabbit["RabbitMQ"]
end

node_client(("Client"))

node_client -->|"sends requests"| node_app
node_app -->|"resolves tenant"| node_tenant
node_app -->|"authenticates requests"| node_authmw
node_app -->|"routes requests"| node_org_routes
node_app -->|"routes requests"| node_project_routes
node_app -->|"routes requests"| node_task_routes
node_app -->|"routes requests"| node_auth_routes
node_app -->|"handles webhook"| node_billing_controller
node_org_routes -->|"dispatches"| node_org_controller
node_project_routes -->|"dispatches"| node_project_controller
node_task_routes -->|"dispatches"| node_task_controller
node_auth_routes -->|"dispatches"| node_auth_controller
node_org_controller -->|"calls"| node_org_service
node_project_controller -->|"calls"| node_project_service
node_task_controller -->|"calls"| node_task_service
node_auth_controller -->|"calls"| node_auth_service
node_org_routes -->|"resolves tenant"| node_tenant
node_org_routes -->|"authenticates requests"| node_authmw
node_org_routes -->|"checks roles"| node_authorize
node_billing_controller -->|"calls"| node_billing_service
node_billing_controller -->|"verifies webhook"| node_stripe_config
node_auth_service -->|"queries"| node_db_config
node_db_config -->|"reads and writes"| node_postgres
node_migrations -->|"defines policies"| node_postgres
node_auth_service -->|"sends mail"| node_email
node_email -->|"delivers mail"| node_resend
node_tenant -.->|"looks up cached tenant"| node_redis_config
node_redis_config -.->|"reads and writes"| node_redis
node_billing_service -.->|"uses billing API"| node_stripe_config
node_stripe_config -.->|"calls"| node_stripe
node_app -->|"reports errors"| node_sentry

click node_app "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/app.js"
click node_tenant "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/middleware/tenant.js"
click node_authmw "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/middleware/auth.js"
click node_authorize "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/middleware/authorize.js"
click node_org_routes "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/organizations/organization.routes.js"
click node_org_controller "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/organizations/organization.controller.js"
click node_org_service "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/organizations/organization.service.js"
click node_project_routes "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/projects/project.routes.js"
click node_project_controller "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/projects/project.controller.js"
click node_project_service "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/projects/project.service.js"
click node_task_routes "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/tasks/task.routes.js"
click node_task_controller "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/tasks/task.controller.js"
click node_task_service "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/tasks/task.service.js"
click node_auth_routes "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/auth/auth.routes.js"
click node_auth_controller "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/auth/auth.controller.js"
click node_auth_service "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/auth/auth.service.js"
click node_db_config "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/config/db.js"
click node_migrations "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/database/migrations/002_tasks_and_rls.sql"
click node_redis_config "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/config/redis.js"
click node_email "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/lib/email.js"
click node_billing_controller "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/billing/billing.controller.js"
click node_billing_service "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/billing/billing.service.js"
click node_stripe_config "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/config/stripe.js"
click node_sentry "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/config/sentry.js"
click node_rabbit_config "https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/config/rabbitmq.js"

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_app,node_tenant,node_authmw,node_authorize,node_client toneBlue
class node_auth_routes,node_auth_controller,node_auth_service toneAmber
class node_org_routes,node_org_controller,node_org_service,node_project_routes,node_project_controller,node_project_service,node_task_routes,node_task_controller,node_task_service,node_db_config,node_postgres,node_migrations toneMint
class node_redis_config,node_redis,node_email,node_resend,node_billing_controller,node_billing_service,node_stripe_config,node_stripe,node_sentry,node_rabbit_config,node_rabbit toneRose
```

## Components

### API and access

- [Express API](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/app.js): `src/app.js`
- [Tenant resolver](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/middleware/tenant.js): `src/middleware/tenant.js`
- [Access auth](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/middleware/auth.js): `src/middleware/auth.js`
- [Role checks](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/middleware/authorize.js): `src/middleware/authorize.js`

### Identity

- [Auth routes](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/auth/auth.routes.js): `src/modules/auth/auth.routes.js`
- [Auth API](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/auth/auth.controller.js): `src/modules/auth/auth.controller.js`
- [Auth service](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/auth/auth.service.js): `src/modules/auth/auth.service.js`

### Workspace data

- [Organization routes](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/organizations/organization.routes.js): `src/modules/organizations/organization.routes.js`
- [Organization API](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/organizations/organization.controller.js): `src/modules/organizations/organization.controller.js`
- [Organization service](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/organizations/organization.service.js): `src/modules/organizations/organization.service.js`
- [Project routes](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/projects/project.routes.js): `src/modules/projects/project.routes.js`
- [Project API](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/projects/project.controller.js): `src/modules/projects/project.controller.js`
- [Project service](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/projects/project.service.js): `src/modules/projects/project.service.js`
- [Task routes](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/tasks/task.routes.js): `src/modules/tasks/task.routes.js`
- [Task API](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/tasks/task.controller.js): `src/modules/tasks/task.controller.js`
- [Task service](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/tasks/task.service.js): `src/modules/tasks/task.service.js`
- [Database access](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/config/db.js): `src/config/db.js`
- **PostgreSQL with RLS**
- [RLS schema](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/database/migrations/002_tasks_and_rls.sql): `database/migrations/002_tasks_and_rls.sql`

### External services

- [Redis client](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/config/redis.js): `src/config/redis.js`
- **Redis cache**
- [Email delivery](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/lib/email.js): `src/lib/email.js`
- **Resend**
- [Billing API](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/billing/billing.controller.js): `src/modules/billing/billing.controller.js`
- [Billing service](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/modules/billing/billing.service.js): `src/modules/billing/billing.service.js`
- [Stripe client](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/config/stripe.js): `src/config/stripe.js`
- **Stripe**
- [Sentry reporting](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/config/sentry.js): `src/config/sentry.js`
- [RabbitMQ client](https://github.com/amanxchaubey/multi-tenant-saas/blob/main/src/config/rabbitmq.js): `src/config/rabbitmq.js`
- **RabbitMQ**

### Other components

- **Client**

## Connections

- Client → Express API: sends requests
- Express API → Tenant resolver: resolves tenant
- Express API → Access auth: authenticates requests
- Express API → Organization routes: routes requests
- Express API → Project routes: routes requests
- Express API → Task routes: routes requests
- Express API → Auth routes: routes requests
- Express API → Billing API: handles webhook
- Organization routes → Organization API: dispatches
- Project routes → Project API: dispatches
- Task routes → Task API: dispatches
- Auth routes → Auth API: dispatches
- Organization API → Organization service: calls
- Project API → Project service: calls
- Task API → Task service: calls
- Auth API → Auth service: calls
- Organization routes → Tenant resolver: resolves tenant
- Organization routes → Access auth: authenticates requests
- Organization routes → Role checks: checks roles
- Billing API → Billing service: calls
- Billing API → Stripe client: verifies webhook
- Auth service → Database access: queries
- Database access → PostgreSQL with RLS: reads and writes
- RLS schema → PostgreSQL with RLS: defines policies
- Auth service → Email delivery: sends mail
- Email delivery → Resend: delivers mail
- Tenant resolver → Redis client: looks up cached tenant
- Redis client → Redis cache: reads and writes
- Billing service → Stripe client: uses billing API
- Stripe client → Stripe: calls
- Express API → Sentry reporting: reports errors