High-Level Design — Workspace

1. Обзор архитектуры

Микросервисная система для управления личными финансами с интеграцией Telegram WebApp.

Стек: NestJS 11, Fastify, gRPC, TypeScript 5, Prisma, PostgreSQL, Redis, Docker Compose, npm workspaces

Принципы:

Каждый сервис — независимый контейнер со своей схемой БД
Межсервисная коммуникация — только gRPC
Единая точка входа для клиентов — API Gateway (REST/HTTP)
Общие типы, proto-файлы и паттерны — в пакете @workspace/shared

2. Системная архитектура

[Diagram]

3. Сервисы

Сервис	Протокол	Порт	Назначение	База данных	Зависит от
API Gateway	HTTP/REST	6001	Точка входа, JWT-аутентификация, Swagger, rate limiting	—	Auth, User, Finance
Auth Service	gRPC	6002	Генерация и валидация JWT-токенов, управление сессиями	Redis	User
Telegram Bot	HTTP	6003	Интеграция с Telegram, команда `/start`	—	Auth, User
User Service	gRPC	6004	CRUD профилей пользователей	PostgreSQL (`user`)	—
Currency Service	gRPC	6005	Валюты, курсы обмена, синхронизация с НБРБ	PostgreSQL (`currency`), Redis	—
Finance Service	gRPC	6006	Счета, транзакции, категории, настройки	PostgreSQL (`finance`), Redis	Currency

4. Межсервисное взаимодействие

[Diagram]

gRPC-пакеты и методы

Пакет	Сервис	Методы
`auth`	AuthService	`FindOrCreate`, `Refresh`, `Revoke`
`user`	UserService	`FindOrCreateByTelegram`, `GetUser`, `UpdateUser`
`currency`	CurrencyService	`GetCurrencies`, `GetExchangeRates`, `GetLastSync`
`finance.account`	AccountService	`CreateAccount`, `GetAccounts`, `GetDeletedAccounts`, `UpdateAccount`, `DeleteAccount`
`finance.transaction`	TransactionService	`CreateTransaction`, `GetTransactions`, `GetTransaction`, `UpdateTransaction`
`finance.transaction`	TransactionItemService	`CreateTransactionItem`, `GetTransactionItems`, `UpdateTransactionItem`, `DeleteTransactionItem`
`finance.provider`	DepositCategoryService	`GetDepositCategories`, `CreateDepositCategory`, `UpdateDepositCategory`, `DeleteDepositCategory`
`finance.provider`	WithdrawalCategoryService	`GetWithdrawalCategories`, `CreateWithdrawalCategory`, `UpdateWithdrawalCategory`, `DeleteWithdrawalCategory`
`finance.settings`	SettingsService	`GetSettings`, `UpdateSettings`
`finance.currency`	FinanceCurrencyService	`GetCurrencies`, `GetExchangeRates`, `GetLastSync`

5. Аутентификация

[Diagram]

6. Слой данных

PostgreSQL — схемы

[Diagram]

Redis

Ключ	Сервис	TTL	Назначение
`refresh:{userId}`	Auth Service	30 дней	Хранение refresh-токенов
Кэш валют	Currency Service	—	Кэш курсов обмена
Кэш валют	Finance Service	—	Локальный кэш курсов

7. Инфраструктура

Docker Compose — порядок запуска

[Diagram]

Стрелки показывают зависимости: A → B означает "A должен быть healthy перед запуском B"

Health Checks

Сервис	Тип проверки
API Gateway	`curl -f http://localhost:{PORT}/docs`
Telegram Bot	HTTP health endpoint
Auth, User, Currency, Finance	TCP-проверка gRPC-порта

CI/CD (Gitea Actions)

Триггер: push в репозиторий
docker compose down — остановка старых контейнеров
Последовательный запуск с билдом: user → auth → currency → finance → api-gateway → telegram-bot
Проверка статуса: docker ps

8. Общий пакет @workspace/shared

packages/shared/
├── proto/                      # gRPC proto-файлы
│   ├── auth.proto
│   ├── user.proto
│   ├── currency.proto
│   ├── finance.account.proto
│   ├── finance.transaction.proto
│   ├── finance.provider.proto
│   ├── finance.currency.proto
│   └── finance.settings.proto
├── src/
│   ├── patterns/               # Константы методов gRPC
│   ├── types/                  # TypeScript DTO-интерфейсы
│   ├── enums/                  # TransactionType и др.
│   └── index.ts                # Токены сервисов, пути к proto

Экспортируемые токены:

AUTH_SERVICE, USER_SERVICE, CURRENCY_SERVICE, FINANCE_SERVICE

9. Структура проекта

workspace/
├── docker-compose.yml
├── package.json                # npm workspaces
├── packages/
│   └── shared/                 # @workspace/shared
├── services/
│   ├── api-gateway/            # HTTP → gRPC прокси
│   ├── auth-service/           # JWT-аутентификация
│   ├── telegram-bot/           # Telegram-интеграция
│   ├── user-service/           # Пользователи (Prisma)
│   ├── currency-service/       # Валюты (Prisma)
│   └── finance-service/        # Финансы (Prisma)
└── HLD.md