# cassperrr/nestjs-project architecture

> Architecture diagram of the GitHub repository cassperrr/nestjs-project, 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/cassperrr/nestjs-project
- Repository: https://github.com/cassperrr/nestjs-project

## Overview

This NestJS monorepo provides a financial and account backend through a gateway and seven cooperating services. The principal path is a client request through the gateway to identity/account or transaction operations, with balance changes coordinated across services; related branches handle avatar storage, scheduled balance resets, email OTPs, and real-time transaction notifications. The graph also shows service-owned persistence and external integrations. Service capabilities and several cross-service links are documented in the README; the sampled source confirms gateway routing, OTP email dispatch, and file upload behavior, but does not expose every service implementation.

Main entry points: [`apps/user-service/src/user-service.module.ts`](https://github.com/cassperrr/nestjs-project/blob/main/apps/user-service/src/user-service.module.ts) (User service), [`apps/gateway/src/gateway.module.ts`](https://github.com/cassperrr/nestjs-project/blob/main/apps/gateway/src/gateway.module.ts) (Gateway API), [`apps/transaction-service/src/transaction-service.module.ts`](https://github.com/cassperrr/nestjs-project/blob/main/apps/transaction-service/src/transaction-service.module.ts) (Transaction service), [`apps/user-service/src/feat/auth/auth.service.ts`](https://github.com/cassperrr/nestjs-project/blob/main/apps/user-service/src/feat/auth/auth.service.ts) (Auth workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Request entry"]
  node_gateway["Gateway API<br/>[gateway.module.ts]"]
end

subgraph group_identity["Identity and accounts"]
  node_user["User service"]
  node_auth["Auth workflows<br/>[auth.service.ts]"]
  node_account["Account and profiles<br/>[account.service.ts]"]
  node_userbalance["Balance management<br/>[balance.service.ts]"]
  node_userdb[("User database<br/>[prisma.module.ts]")]
  node_redis[("Redis state<br/>[redis.module.ts]")]
end

subgraph group_finance["Financial operations"]
  node_transaction["Transaction service"]
  node_txdb[("Transaction database<br/>[prisma.module.ts]")]
end

subgraph group_support["Supporting services"]
  node_file["File service<br/>[file.module.ts]"]
  node_storage[("S3 avatar storage")]
  node_job["Job service<br/>[job.module.ts]"]
  node_queue["Balance reset queue<br/>[queue.service.ts]"]
  node_mail["Mail service<br/>[mail.controller.ts]"]
  node_notification["Notification service"]
  node_mongo[("Notification history<br/>[mongo.module.ts]")]
end

subgraph group_shared["Shared infrastructure"]
  node_contracts["Service contracts"]
  node_grpc["gRPC integration"]
end

node_client(("Client"))
node_yookassa["Yookassa"]
node_smtp["SMTP mail transport"]
node_websocket(("WebSocket clients"))

node_client -->|"sends requests"| node_gateway
node_gateway -->|"routes gRPC"| node_user
node_gateway -->|"routes gRPC"| node_transaction
node_gateway -->|"proxies files"| node_file
node_user -->|"handles identity"| node_auth
node_user -->|"handles accounts"| node_account
node_user -->|"handles balances"| node_userbalance
node_auth -->|"reads and writes"| node_userdb
node_auth -->|"stores sessions and OTPs"| node_redis
node_user -->|"persists user data"| node_userdb
node_user -->|"caches user data"| node_redis
node_user -->|"sends OTP events"| node_mail
node_mail -->|"sends email"| node_smtp
node_user -->|"publishes events"| node_notification
node_notification -->|"stores history"| node_mongo
node_notification -->|"pushes notifications"| node_websocket
node_user -->|"requests jobs"| node_job
node_job -->|"schedules resets"| node_queue
node_job -->|"requests balance reset"| node_userbalance
node_transaction -->|"records transactions"| node_txdb
node_transaction -.->|"integrates payments"| node_yookassa
node_user -->|"exchanges saga events"| node_transaction
node_file -->|"streams avatar files"| node_storage
node_gateway -->|"uses clients"| node_grpc
node_gateway -.->|"uses service contracts"| node_contracts

click node_gateway "https://github.com/cassperrr/nestjs-project/blob/main/apps/gateway/src/gateway.module.ts"
click node_user "https://github.com/cassperrr/nestjs-project/blob/main/apps/user-service/src/user-service.module.ts"
click node_auth "https://github.com/cassperrr/nestjs-project/blob/main/apps/user-service/src/feat/auth/auth.service.ts"
click node_account "https://github.com/cassperrr/nestjs-project/blob/main/apps/user-service/src/feat/account/account.service.ts"
click node_userbalance "https://github.com/cassperrr/nestjs-project/blob/main/apps/user-service/src/feat/balance/balance.service.ts"
click node_userdb "https://github.com/cassperrr/nestjs-project/blob/main/apps/user-service/src/infra/prisma/prisma.module.ts"
click node_redis "https://github.com/cassperrr/nestjs-project/blob/main/apps/user-service/src/infra/redis/redis.module.ts"
click node_transaction "https://github.com/cassperrr/nestjs-project/blob/main/apps/transaction-service/src/transaction-service.module.ts"
click node_txdb "https://github.com/cassperrr/nestjs-project/blob/main/apps/transaction-service/src/infra/prisma/prisma.module.ts"
click node_file "https://github.com/cassperrr/nestjs-project/blob/main/apps/file-service/src/file.module.ts"
click node_storage "https://github.com/cassperrr/nestjs-project/blob/main/apps/file-service/src/infra/storage/s3/s3-stream.storage.ts"
click node_job "https://github.com/cassperrr/nestjs-project/blob/main/apps/job-service/src/job.module.ts"
click node_queue "https://github.com/cassperrr/nestjs-project/blob/main/apps/job-service/src/core/queue/queue.service.ts"
click node_mail "https://github.com/cassperrr/nestjs-project/blob/main/apps/mail-service/src/mail.controller.ts"
click node_notification "https://github.com/cassperrr/nestjs-project/blob/main/apps/notification-service/src/notification-service.module.ts"
click node_mongo "https://github.com/cassperrr/nestjs-project/blob/main/apps/notification-service/src/infra/mongo/mongo.module.ts"
click node_contracts "https://github.com/cassperrr/nestjs-project/tree/main/contracts"
click node_grpc "https://github.com/cassperrr/nestjs-project/tree/main/libs/grpc"

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_gateway,node_client,node_websocket toneBlue
class node_user,node_auth,node_account,node_userbalance,node_userdb,node_redis toneAmber
class node_transaction,node_txdb toneMint
class node_file,node_storage,node_job,node_queue,node_mail,node_notification,node_mongo toneRose
class node_contracts,node_grpc,node_yookassa,node_smtp toneIndigo
```

## Components

### Request entry

- [Gateway API](https://github.com/cassperrr/nestjs-project/blob/main/apps/gateway/src/gateway.module.ts): `apps/gateway/src/gateway.module.ts`

### Identity and accounts

- [User service](https://github.com/cassperrr/nestjs-project/blob/main/apps/user-service/src/user-service.module.ts): `apps/user-service/src/user-service.module.ts`
- [Auth workflows](https://github.com/cassperrr/nestjs-project/blob/main/apps/user-service/src/feat/auth/auth.service.ts): `apps/user-service/src/feat/auth/auth.service.ts`
- [Account and profiles](https://github.com/cassperrr/nestjs-project/blob/main/apps/user-service/src/feat/account/account.service.ts): `apps/user-service/src/feat/account/account.service.ts`
- [Balance management](https://github.com/cassperrr/nestjs-project/blob/main/apps/user-service/src/feat/balance/balance.service.ts): `apps/user-service/src/feat/balance/balance.service.ts`
- [User database](https://github.com/cassperrr/nestjs-project/blob/main/apps/user-service/src/infra/prisma/prisma.module.ts): `apps/user-service/src/infra/prisma/prisma.module.ts`
- [Redis state](https://github.com/cassperrr/nestjs-project/blob/main/apps/user-service/src/infra/redis/redis.module.ts): `apps/user-service/src/infra/redis/redis.module.ts`

### Financial operations

- [Transaction service](https://github.com/cassperrr/nestjs-project/blob/main/apps/transaction-service/src/transaction-service.module.ts): `apps/transaction-service/src/transaction-service.module.ts`
- [Transaction database](https://github.com/cassperrr/nestjs-project/blob/main/apps/transaction-service/src/infra/prisma/prisma.module.ts): `apps/transaction-service/src/infra/prisma/prisma.module.ts`

### Supporting services

- [File service](https://github.com/cassperrr/nestjs-project/blob/main/apps/file-service/src/file.module.ts): `apps/file-service/src/file.module.ts`
- [S3 avatar storage](https://github.com/cassperrr/nestjs-project/blob/main/apps/file-service/src/infra/storage/s3/s3-stream.storage.ts): `apps/file-service/src/infra/storage/s3/s3-stream.storage.ts`
- [Job service](https://github.com/cassperrr/nestjs-project/blob/main/apps/job-service/src/job.module.ts): `apps/job-service/src/job.module.ts`
- [Balance reset queue](https://github.com/cassperrr/nestjs-project/blob/main/apps/job-service/src/core/queue/queue.service.ts): `apps/job-service/src/core/queue/queue.service.ts`
- [Mail service](https://github.com/cassperrr/nestjs-project/blob/main/apps/mail-service/src/mail.controller.ts): `apps/mail-service/src/mail.controller.ts`
- [Notification service](https://github.com/cassperrr/nestjs-project/blob/main/apps/notification-service/src/notification-service.module.ts): `apps/notification-service/src/notification-service.module.ts`
- [Notification history](https://github.com/cassperrr/nestjs-project/blob/main/apps/notification-service/src/infra/mongo/mongo.module.ts): `apps/notification-service/src/infra/mongo/mongo.module.ts`

### Shared infrastructure

- [Service contracts](https://github.com/cassperrr/nestjs-project/tree/main/contracts): `contracts`
- [gRPC integration](https://github.com/cassperrr/nestjs-project/tree/main/libs/grpc): `libs/grpc`

### Other components

- **Client**
- **Yookassa**
- **SMTP mail transport**
- **WebSocket clients**

## Connections

- Client → Gateway API: sends requests
- Gateway API → User service: routes gRPC
- Gateway API → Transaction service: routes gRPC
- Gateway API → File service: proxies files
- User service → Auth workflows: handles identity
- User service → Account and profiles: handles accounts
- User service → Balance management: handles balances
- Auth workflows → User database: reads and writes
- Auth workflows → Redis state: stores sessions and OTPs
- User service → User database: persists user data
- User service → Redis state: caches user data
- User service → Mail service: sends OTP events
- Mail service → SMTP mail transport: sends email
- User service → Notification service: publishes events
- Notification service → Notification history: stores history
- Notification service → WebSocket clients: pushes notifications
- User service → Job service: requests jobs
- Job service → Balance reset queue: schedules resets
- Job service → Balance management: requests balance reset
- Transaction service → Transaction database: records transactions
- Transaction service → Yookassa: integrates payments
- User service → Transaction service: exchanges saga events
- File service → S3 avatar storage: streams avatar files
- Gateway API → gRPC integration: uses clients
- Gateway API → Service contracts: uses service contracts