Карта API проєкту
Один екран — усі точки HTTP-входу всіх бек-сервісів. Кожен сервіс описує свій контракт у власному Swagger UI; ця сторінка — індекс.
Правило: API-контракт ендпоінтів живе в Swagger, а не в markdown. У сервісних доках — тільки бізнес-нюанси яких Swagger не показує (рідкісні комбінації гвардів, legacy-конвенції, кваркові побічні ефекти). Все інше — клік на Swagger UI.
Swagger UIs
| Сервіс | Локально | Прод | Стан міграції |
|---|---|---|---|
| stack-golden | http://localhost:81/golden/api-docs/v2 | api.besocial.tech/golden/api-docs/v2 | у процесі — частина на routing-controllers, решта legacy BaseController (поза Swagger) |
| stack-academy | http://localhost:<port>/academy/api-docs | TBD | NestJS, один Swagger |
| stack-ai | http://localhost:3001/stack-ai/api-docs | TBD | NestJS, один Swagger |
| stack | — | — | TODO |
| stack-prime | — | — | TODO |
| stack-udate | — | — | TODO |
| stack-chathouse | — | — | TODO |
Кінцева мета — кожен бек-сервіс має один auto-Swagger UI на /<service>/api-docs[/v2]. Чек-ліст міграції — у CLAUDE.md репо stack-golden (секція «Як мігрувати legacy-контролер на routing-controllers»).
Конвенція відповідей (єдина для всього стеку)
Усі бек-сервіси відповідають HTTP 200 з body одного з двох форматів:
// success
{ "success": true, "data": <payload> }
// error (через ExeptionFilter або throw HTTPError)
{ "success": false, "data": null|<data>, "message": "...", "statusCode": <code>, "context": "..." }Реальний код помилки — у полі statusCode тіла, не у HTTP-статусі. Клієнт орієнтується на success, не на HTTP status. Це legacy-конвенція проєкту, не змінюємо.
Винятки (зашиті в stack-commons):
MiddlevareGuardбез потрібної ролі → HTTP 400 +{success:false, data:{message:'Not allow role'}}MiddlevareGuardбез токена → HTTP 401 з порожнім body
В AI/Academy (NestJS) виняток — RolesGuard повертає HTTP 403 через ForbiddenException (а не 200 з success:false). Це NestJS-deviation від загального правила.
Auth
JWT видає stack. Кожен бек розгортає MiddlevareAuth з stack-commons — кладе req.user якщо токен валідний, не блокуючи запит без токена. Захист — на рівні ендпоінта через guard([roles]) (RC) / @ApiRoles([roles]) (NestJS).
Важливий нюанс: і RolesGuard (NestJS), і MiddlevareGuard (legacy) пропускають запит коли відповідного декоратора нема. Тобто @UseGuards(RolesGuard) без @ApiRoles = публічний ендпоінт. Уважно з цим.
Формати між сервісами
Описують крос-сервісні структури які ходять через RMQ або через stack як проксі.
TODO: задокументувати ключові payloads — UserSignup, AcademyDropUsers, AcademyGetMentors.query, family-events, статистики від electron → stack. Зараз пляма.
Локальні entities кожного сервісу — у <service>/docs/entities/ і в root entities.
Зв’язки
- Огляд топології → Architecture
- Pipeline доки → Docs Pipeline
- Ролі → roles