АРХ - NODEDC PLATFORM: каркас платформенного репозитория

2026-05-04 10:02:18 +03:00
commit 0f89c4d126
12 changed files with 755 additions and 0 deletions
@@ -0,0 +1,109 @@
+# Architecture: NODE.DC Multi-App Platform
+
+## Цель
+
+Собрать единую платформенную основу для Launcher, Task Manager / Plane и будущих приложений NODE.DC.
+
+Целевой пользовательский сценарий:
+
+1. Пользователь открывает Launcher.
+2. Если сессии нет, его отправляет в Authentik.
+3. После логина Launcher получает identity и app access.
+4. Launcher показывает только доступные приложения.
+5. Переход в Task Manager не требует повторного логина.
+6. Прямой URL Task Manager тоже защищен.
+
+## Роли компонентов
+
+`Authentik` является единым Identity Provider:
+
+- логин;
+- пароль;
+- активность пользователя;
+- группы;
+- app access;
+- OIDC claims;
+- будущие invite/enrollment/MFA flows.
+
+`Launcher` является control plane:
+
+- входная точка пользователя;
+- список доступных приложений;
+- admin UI управления пользователями и доступами;
+- backend-интеграция с Authentik API;
+- audit log админских действий.
+
+`Task Manager / Plane` остается отдельным приложением:
+
+- собственная БД;
+- собственные workspace/project/task/comment модели;
+- собственные роли workspace/project;
+- OIDC login через Authentik;
+- mapping внешней identity на существующего Plane user.
+
+`Reverse proxy` является внешним защитным и маршрутизирующим слоем:
+
+- единая точка входа;
+- HTTPS в staging/production;
+- routing по app domain;
+- forward headers для Authentik;
+- deny для пользователей без app access.
+
+## Repository layout
+
+Рабочая схема:
+
+```text
+NODEDC/
+  DOC/
+  platform/
+    docs/
+    infra/
+    packages/
+    tasks/
+
+/Users/dcconstructions/Downloads/mnt/data/nodedc_launcher
+/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER
+```
+
+`platform/` не забирает исходники Launcher и Plane внутрь себя. Он хранит только платформенный слой и договоренности между приложениями.
+
+## Data ownership
+
+Не создается единая общая таблица `users` для всех приложений.
+
+Логическая схема:
+
+```text
+authentik_db     -> identity, groups, app access
+launcher_db      -> app registry, local profiles, audit
+plane_db         -> workspace, projects, tasks, comments, app roles
+future_app_db    -> доменная логика будущих приложений
+```
+
+Связь между identity и локальными пользователями выполняется через explicit mapping, а не через прямое чтение чужих таблиц.
+
+## Auth flow
+
+Для приложений, которые контролируются кодом:
+
+- OIDC Authorization Code Flow + PKCE;
+- backend/session или BFF layer;
+- JWT/JWKS validation server-side;
+- проверка `issuer`, `audience`, `exp`, `sub`;
+- проверка app access group;
+- локальный user profile или external identity link.
+
+Для legacy/временных приложений допускается reverse proxy forward-auth, но это временный внешний слой, а не единственная долгосрочная модель.
+
+## Plane migration rule
+
+Существующий Plane user нельзя пересоздавать.
+
+Нужен mapping:
+
+```text
+authentik_user.sub -> existing plane_user.id
+```
+
+Plane должен логинить существующего пользователя по link, сохраняя все старые workspace, assignee, owner, created_by, comments и attachments.