Огляд системи

Інтерфейс у браузері --> Next.js вебзастосунок ----------------> Postgres (RLS)
Машинні клієнти      --> API Gateway (REST) --> SQL Lambda ---------^
MCP-клієнти          --> API Gateway (HTTP) --> MCP Lambda ---------^
Сервіс автентифікації (OTP + OAuth) -------------------------------^
Worker (оновлення курсів FX) --------------------------------------^

Архітектура складається із шести компонентів, які працюють з однією базою даних:

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

Модель даних

ledger_entries — один рядок на кожен рух коштів за рахунком: дохід, витрату або переказ
budget_lines — бюджетні комірки з моделлю append-only; під час читання використовується останній запис
budget_comments — примітки до бюджетних комірок, які також зберігаються у форматі append-only
workspace_settings — валюта звітності й налаштування на рівні робочого простору
account_metadata — метадані окремих рахунків, наприклад класифікація ліквідності
exchange_rates — щоденні валютні курси, які використовуються для конвертації під час виконання запиту
workspaces / workspace_members — ізоляція між окремими робочими просторами
accounts — подання, сформоване на основі записів у журналі операцій

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

Усі суми зберігаються у вихідній валюті. Перерахунок у валюту звітності відбувається під час читання через SQL JOIN з exchange_rates. Попередня конвертація, яка могла б призвести до втрати точності, не використовується.

Автентифікація

Режим автентифікації визначається змінною середовища AUTH_MODE:

none — без автентифікації, з одним локальним робочим простором
cognito — безпарольний вхід через одноразовий код, надісланий електронною поштою, у AWS Cognito з відкритою реєстрацією

Для машинних клієнтів публічною точкою входу для виявлення сервісу є GET /v1/. Початкове підключення агентів відбувається на домені автентифікації за одноразовим кодом, надісланим електронною поштою: у відповідь клієнт отримує довгоживучий ApiKey, після чого виконує SQL через машинний API за API Gateway.

MCP-клієнти підключаються окремо до https://mcp.expense-budget-tracker.com/mcp. Цей шлях обслуговують виділені HTTP API в API Gateway і MCP Lambda, а інтерактивна авторизація відбувається через OAuth у браузері на домені автентифікації.

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