# Architecture

`identity-gateway` is an internal authority for identity across the SaaS platform. It sits between
human users and internal services, issuing trusted JWTs for service-to-service access.

## Core responsibilities

- Central authentication and authorization.
- RBAC and permission enforcement per tenant.
- Token issuance for trusted backend services.
- Provider-agnostic identity validation (local/external).

## Components

- **Auth module**: Handles login, refresh, and logout flows.
- **Users module**: Maintains internal user identities and tenant membership.
- **Roles & Permissions**: Defines RBAC primitives and tenant-specific grants.
- **Sessions**: Stores refresh token sessions.
- **Core guards**: Enforces authentication, roles, and permissions.

## Trust boundaries

- Only internal services validate JWTs issued by the gateway.
- JWTs are not intended for public client apps without a proxy.

## Data flow

1. User authenticates with `identity-gateway`.
2. Gateway validates identity via provider and maps user to tenant.
3. Gateway issues access + refresh tokens.
4. Internal services validate access token claims.