Архітектура проєкту
Мапа всіх сервісів і їх взаємодій. Тут описуємо топологію — хто з ким говорить і яким каналом. Глибина окремого сервісу — у його власному <service>/docs/.
Візуальна мапа — Canvas.
Сервіси
| Сервіс | Тип | Роль у системі |
|---|---|---|
| stack | Бек, точка входу | Оркестратор, auth, маршрутизація між проєктами |
| stack-client | Фронт (web) | Веб-інтерфейс для всіх ролей |
| stack-electron | Електрон-клієнт | Робоче місце оператора |
| stack-golden | Бек | Логіка проєкту goldenbride |
| stack-prime | Бек | Логіка проєкту prime |
| stack-udate | Бек | Логіка проєкту udate |
| stack-chathouse | Бек | Логіка проєкту chathouse |
| stack-academy | Бек | Внутрішня школа |
| stack-ai | Бек | AI-функції |
stack-commons | Бібліотека | Спільні middleware, types, утиліти. Власних docs не має. |
Сервіси
golden / prime / udate / chathouseструктурно схожі — кожен реалізує бізнес-логіку для свого партнерського проєкту. Спільні патерни описуємо тут, специфічне — у локальних доках.
Канали взаємодії
- HTTP — синхронні виклики, переважно фронт ↔ бек і electron ↔ бек.
- RMQ — асинхронна шина для обміну подіями між бек-сервісами. (TODO: задокументувати схему черг)
- Спільна БД / Redis / ClickHouse — (TODO: де які стори, що шарується)
Auth і ролі
Авторизація проходить через stack, видається JWT. Кожен бек-сервіс розгортає MiddlevareAuth (з stack-commons) який кладе req.user якщо токен валідний — не блокуючи запит без токена. Захист на рівні ендпоінта — через guard([roles]).
Ролі — у roles.
Конвенція HTTP-відповідей
Усі бек-сервіси відповідають HTTP 200 з body одного з форматів:
// success
{ "success": true, "data": <payload> }
// error (через ExeptionFilter або throw HTTPError з stack-commons)
{ "success": false, "data": null|<data>, "message": "...", "statusCode": <code>, "context": "..." }Виняток: MiddlevareGuard без потрібної ролі віддає HTTP 400 + {success:false, data:{message:'Not allow role'}}. Без токена — HTTP 401 з порожнім body.
Стан міграції на auto-Swagger
| Сервіс | Статус |
|---|---|
| stack-golden | у процесі — частина контролерів на routing-controllers, v2 Swagger |
| stack | TODO |
| stack-prime | TODO |
| stack-udate | TODO |
| stack-chathouse | TODO |
| stack-ai | TODO |
| stack-academy | TODO |
Кінцева мета — у кожному бек-сервісі один auto-Swagger UI на /<service>/api-docs/v2. Чек-ліст міграції — у CLAUDE.md репо стартового сервісу (stack-golden).