Обзор системы

Браузерный интерфейс --> Веб-приложение Next.js ----------------> Postgres (RLS)
Программные клиенты  --> API Gateway (REST) --> SQL Lambda ----------^
MCP-клиенты          --> API Gateway (HTTP) --> MCP Lambda ----------^
Сервис аутентификации (OTP + OAuth) ---------------------------------^
Воркер (загрузка валютных курсов) -----------------------------------^

Шесть компонентов, одна база данных:

web — приложение на Next.js с пользовательскими дашбордами и API-маршрутами
auth — вход по одноразовому коду из email и начальное подключение агентов на auth-домене
sql-api — AWS Lambda за API Gateway для программных клиентов
mcp — отдельные AWS Lambda и HTTP API в API Gateway для размещенной точки MCP
worker — ежедневная загрузка курсов ECB, CBR и NBS
Postgres — единый источник истины с политиками RLS

Модель данных

ledger_entries — одна строка на каждое движение по счёту: доход, расход или перевод
budget_lines — ячейки бюджета в модели только с добавлением записей; при конфликте действует правило «последняя запись побеждает»
budget_comments — заметки к ячейкам бюджета в модели только с добавлением записей
workspace_settings — отчётная валюта и настройки рабочего пространства
account_metadata — метаданные по счетам, например классификация ликвидности
exchange_rates — ежедневные валютные курсы для конвертации во время запроса
workspaces / workspace_members — изоляция арендаторов в многопользовательской схеме
accounts — представление, построенное на основе ledger_entries

Мультивалютность

Все суммы хранятся в исходной валюте. Пересчёт в отчётную валюту выполняется во время чтения через SQL-соединения с exchange_rates. Предварительной конвертации с потерей точности нет.

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

Через переменную окружения AUTH_MODE доступны два режима:

none — без аутентификации, одно локальное рабочее пространство
cognito — беспарольный вход по одноразовому коду из email через AWS Cognito с открытой регистрацией

Для программных клиентов публичной точкой входа служит GET /v1/. Подключение агента использует одноразовый код из email на auth-домене, возвращает долгоживущий ApiKey, а затем выполняет SQL через отдельный API для программных клиентов за API Gateway.

MCP-клиенты подключаются отдельно к https://mcp.expense-budget-tracker.com/mcp. Этот путь обслуживают выделенные HTTP API в API Gateway и MCP Lambda, а интерактивная авторизация проходит через OAuth в браузере на auth-домене.

Каждый пользователь получает изолированное рабочее пространство. Политики RLS проверяют членство при каждом запросе, включая SQL-запросы от программных клиентов.