# safeer-jan/be-nest-authservice architecture

> Architecture diagram of the GitHub repository safeer-jan/be-nest-authservice, 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/safeer-jan/be-nest-authservice
- Repository: https://github.com/safeer-jan/be-nest-authservice

## Overview

This is a reusable NestJS authentication service. Clients register or log in through the local auth API to receive an access/refresh-token pair; refresh rotates the opaque token, while logout and password changes revoke sessions. Separate branches support account and profile management, administrative RBAC, and optional AWS Cognito identity flows. The sampled sources establish the core service calls and persistence; several README-documented capabilities have no sampled implementation excerpt, so uncertain internal wiring is omitted.

Main entry points: [`src/modules/auth/auth.service.ts`](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/auth/auth.service.ts) (Auth service), [`src/modules/auth/auth.controller.ts`](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/auth/auth.controller.ts) (Auth API), [`src/modules/users/users.service.ts`](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/users/users.service.ts) (Users service), [`src/modules/rbac/roles.service.ts`](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/rbac/roles.service.ts) (Roles service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_auth["Local authentication"]
  node_auth_controller["Auth API<br/>[auth.controller.ts]"]
  node_auth_service["Auth service<br/>[auth.service.ts]"]
  node_token_service["Token service<br/>[token.service.ts]"]
  node_local_guard["Local login guard"]
end

subgraph group_accounts["Accounts and RBAC"]
  node_users_controller["Users API"]
  node_users_service["Users service<br/>[users.service.ts]"]
  node_user_entity["User records<br/>[user.entity.ts]"]
  node_roles_controller["Roles API"]
  node_roles_service["Roles service<br/>[roles.service.ts]"]
  node_permissions_service["Permissions service"]
  node_role_entity["Role records<br/>[role.entity.ts]"]
  node_permission_entity["Permission records"]
end

subgraph group_runtime["Runtime security"]
  node_app["Nest app<br/>[app.module.ts]"]
  node_jwt_guard["JWT guard<br/>[jwt-auth.guard.ts]"]
  node_redis_service["Redis service<br/>[redis.service.ts]"]
end

subgraph group_integrations["External integrations"]
  node_cognito_controller["Cognito API"]
  node_cognito_service["Cognito service<br/>[cognito.service.ts]"]
  node_cognito_guard["Cognito JWT guard"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
  node_aws_cognito["AWS Cognito"]
end

node_client(("API client"))

node_client -->|"requests auth"| node_auth_controller
node_auth_controller -->|"handles auth"| node_auth_service
node_auth_controller -->|"guards login"| node_local_guard
node_local_guard -->|"validates credentials"| node_auth_service
node_auth_service -->|"loads and creates users"| node_users_service
node_auth_service -->|"issues and hashes tokens"| node_token_service
node_auth_service -->|"stores session tokens"| node_postgres
node_auth_service -->|"invalidates cache"| node_redis_service
node_token_service -->|"supports token responses"| node_auth_controller
node_client -->|"requests account changes"| node_users_controller
node_users_controller -->|"manages profiles and roles"| node_users_service
node_users_service -->|"reads and writes users"| node_postgres
node_users_service -->|"looks up assigned roles"| node_roles_service
node_client -->|"requests RBAC administration"| node_roles_controller
node_roles_controller -->|"manages roles"| node_roles_service
node_roles_controller -->|"manages permissions"| node_permissions_service
node_roles_service -->|"reads and writes roles"| node_postgres
node_roles_service -->|"loads permissions"| node_permission_entity
node_permissions_service -->|"reads and writes permissions"| node_postgres
node_jwt_guard -->|"checks revocation"| node_redis_service
node_redis_service -->|"reads and writes cache"| node_redis
node_client -.->|"requests Cognito auth"| node_cognito_controller
node_cognito_controller -.->|"handles identity flow"| node_cognito_service
node_cognito_controller -.->|"guards token check"| node_cognito_guard
node_cognito_guard -.->|"verifies token"| node_cognito_service
node_cognito_service -.->|"authenticates and verifies"| node_aws_cognito

click node_app "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/app.module.ts"
click node_auth_controller "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/auth/auth.controller.ts"
click node_auth_service "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/auth/auth.service.ts"
click node_token_service "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/auth/token.service.ts"
click node_local_guard "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/auth/guards/local-auth.guard.ts"
click node_jwt_guard "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/auth/guards/jwt-auth.guard.ts"
click node_users_controller "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/users/users.controller.ts"
click node_users_service "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/users/users.service.ts"
click node_user_entity "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/users/entities/user.entity.ts"
click node_roles_controller "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/rbac/roles.controller.ts"
click node_roles_service "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/rbac/roles.service.ts"
click node_permissions_service "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/rbac/permissions.service.ts"
click node_role_entity "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/rbac/entities/role.entity.ts"
click node_permission_entity "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/rbac/entities/permission.entity.ts"
click node_cognito_controller "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/cognito/cognito.controller.ts"
click node_cognito_service "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/cognito/cognito.service.ts"
click node_cognito_guard "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/cognito/cognito-jwt.guard.ts"
click node_redis_service "https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/redis/redis.service.ts"

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_auth_controller,node_auth_service,node_token_service,node_local_guard,node_client toneBlue
class node_users_controller,node_users_service,node_user_entity,node_roles_controller,node_roles_service,node_permissions_service,node_role_entity,node_permission_entity toneAmber
class node_app,node_jwt_guard,node_redis_service toneMint
class node_cognito_controller,node_cognito_service,node_cognito_guard,node_postgres,node_redis,node_aws_cognito toneRose
```

## Components

### Local authentication

- [Auth API](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/auth/auth.controller.ts): `src/modules/auth/auth.controller.ts`
- [Auth service](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/auth/auth.service.ts): `src/modules/auth/auth.service.ts`
- [Token service](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/auth/token.service.ts): `src/modules/auth/token.service.ts`
- [Local login guard](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/auth/guards/local-auth.guard.ts): `src/modules/auth/guards/local-auth.guard.ts`

### Accounts and RBAC

- [Users API](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/users/users.controller.ts): `src/modules/users/users.controller.ts`
- [Users service](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/users/users.service.ts): `src/modules/users/users.service.ts`
- [User records](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/users/entities/user.entity.ts): `src/modules/users/entities/user.entity.ts`
- [Roles API](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/rbac/roles.controller.ts): `src/modules/rbac/roles.controller.ts`
- [Roles service](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/rbac/roles.service.ts): `src/modules/rbac/roles.service.ts`
- [Permissions service](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/rbac/permissions.service.ts): `src/modules/rbac/permissions.service.ts`
- [Role records](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/rbac/entities/role.entity.ts): `src/modules/rbac/entities/role.entity.ts`
- [Permission records](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/rbac/entities/permission.entity.ts): `src/modules/rbac/entities/permission.entity.ts`

### Runtime security

- [Nest app](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/app.module.ts): `src/app.module.ts`
- [JWT guard](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/auth/guards/jwt-auth.guard.ts): `src/modules/auth/guards/jwt-auth.guard.ts`
- [Redis service](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/redis/redis.service.ts): `src/modules/redis/redis.service.ts`

### External integrations

- [Cognito API](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/cognito/cognito.controller.ts): `src/modules/cognito/cognito.controller.ts`
- [Cognito service](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/cognito/cognito.service.ts): `src/modules/cognito/cognito.service.ts`
- [Cognito JWT guard](https://github.com/safeer-jan/be-nest-authservice/blob/develop/src/modules/cognito/cognito-jwt.guard.ts): `src/modules/cognito/cognito-jwt.guard.ts`
- **PostgreSQL**
- **Redis**
- **AWS Cognito**

### Other components

- **API client**

## Connections

- API client → Auth API: requests auth
- Auth API → Auth service: handles auth
- Auth API → Local login guard: guards login
- Local login guard → Auth service: validates credentials
- Auth service → Users service: loads and creates users
- Auth service → Token service: issues and hashes tokens
- Auth service → PostgreSQL: stores session tokens
- Auth service → Redis service: invalidates cache
- Token service → Auth API: supports token responses
- API client → Users API: requests account changes
- Users API → Users service: manages profiles and roles
- Users service → PostgreSQL: reads and writes users
- Users service → Roles service: looks up assigned roles
- API client → Roles API: requests RBAC administration
- Roles API → Roles service: manages roles
- Roles API → Permissions service: manages permissions
- Roles service → PostgreSQL: reads and writes roles
- Roles service → Permission records: loads permissions
- Permissions service → PostgreSQL: reads and writes permissions
- JWT guard → Redis service: checks revocation
- Redis service → Redis: reads and writes cache
- API client → Cognito API: requests Cognito auth
- Cognito API → Cognito service: handles identity flow
- Cognito API → Cognito JWT guard: guards token check
- Cognito JWT guard → Cognito service: verifies token
- Cognito service → AWS Cognito: authenticates and verifies