Initial commit: MVP structure + Cursor documentation + Onboarding components
This commit is contained in:
Apple
239
docs/cursor/02_architecture_basics.md
Normal file
239
docs/cursor/02_architecture_basics.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# 02 — MicroDAO Architecture Basics (MVP)
|
||||
|
||||
Цей документ дає Cursor і розробникам стисле уявлення про архітектуру MicroDAO, необхідне для реалізації перших функцій MVP.
|
||||
|
||||
## 1. Загальний огляд архітектури
|
||||
|
||||
MicroDAO складається з:
|
||||
|
||||
- **Front-end SPA** (React + TypeScript)
|
||||
- **API Gateway** (`https://api.microdao.xyz/v1`)
|
||||
- **Core Services** (Teams, Channels, Messages, Followups, Projects, Agents)
|
||||
- **PostgreSQL** — основна база даних
|
||||
- **NATS JetStream** — message bus (події, outbox-патерн)
|
||||
- **Meilisearch** — індексація і пошук
|
||||
- **S3-compatible storage** — файли
|
||||
- **WebSockets** — оновлення повідомлень у реальному часі
|
||||
|
||||
Джерела:
|
||||
- Data Model & Event Catalog
|
||||
- Tech Spec / Технічний опис MicroDAO
|
||||
- API Specification (OpenAPI 3.1)
|
||||
|
||||
## 2. Стек MVP
|
||||
|
||||
- **Frontend:** React 18, TypeScript, Vite або Next SPA-режим
|
||||
- **State:** React Query / TanStack Query
|
||||
- **Design System:** базовий UI-компонентний набір (кнопки, поля, layout)
|
||||
- **Backend:** Go або Node (вже залежить від вашої реалізації — Cursor адаптується)
|
||||
- **Auth:** Magic-link email (JWT)
|
||||
- **Transport:** REST + WebSockets
|
||||
|
||||
## 3. Основні модулі
|
||||
|
||||
### 3.1. Auth Service
|
||||
|
||||
- Відповідає за:
|
||||
- `POST /auth/login-email`
|
||||
- `POST /auth/exchange`
|
||||
- Видає JWT (користувач, локаль, tz).
|
||||
- Email з кодом / magic-link відправляє окремий SMTP-модуль.
|
||||
- Після входу SPA зберігає токен та ініціалізує сесію.
|
||||
|
||||
### 3.2. Teams / MicroDAO Service
|
||||
|
||||
- Створення спільноти — автоматично створює micro-DAO:
|
||||
- `POST /teams`
|
||||
- `PATCH /teams/{id}` — public/confidential
|
||||
- Зберігає:
|
||||
- id спільноти
|
||||
- slug
|
||||
- режим (`public`, `confidential`)
|
||||
- Members / Guardians
|
||||
- Взаємодіє з Channels, Messages, Projects, Agents.
|
||||
|
||||
### 3.3. Channels Service
|
||||
|
||||
- Створення каналів:
|
||||
- `POST /channels`
|
||||
- Типи:
|
||||
- `public` — доступні гостям (read-only)
|
||||
- `group` — приватні групові канали
|
||||
- Channel data:
|
||||
- team_id
|
||||
- type
|
||||
- mode (public/confidential)
|
||||
|
||||
### 3.4. Messaging Service
|
||||
|
||||
- Головне ядро MVP.
|
||||
- API:
|
||||
- `GET /channels/{id}/messages`
|
||||
- `POST /channels/{id}/messages`
|
||||
- `PATCH /messages/{id}`
|
||||
- `DELETE /messages/{id}`
|
||||
- Зберігає:
|
||||
- текстові повідомлення
|
||||
- автора (user_id або agent_id)
|
||||
- E2EE шифротекст у confidential режимі
|
||||
- WebSocket транслює нові повідомлення в реальному часі.
|
||||
|
||||
### 3.5. Followups Service
|
||||
|
||||
- Легкий таскер, прив'язаний до повідомлень.
|
||||
- API:
|
||||
- `POST /followups`
|
||||
- `GET /followups?assignee=...`
|
||||
- Статуси:
|
||||
- `open`, `in_progress`, `done`
|
||||
- Використовується для персональних нагадувань і мікро-задач.
|
||||
|
||||
### 3.6. Projects & Tasks Service (Kanban-lite)
|
||||
|
||||
- API:
|
||||
- `POST /projects`
|
||||
- `GET /projects`
|
||||
- `POST /projects/{id}/tasks`
|
||||
- `GET /projects/{id}/tasks`
|
||||
- Статуси задач:
|
||||
- `backlog`, `in_progress`, `review`, `done`
|
||||
- Проста Kanban-дошка для MVP.
|
||||
|
||||
### 3.7. Agents Service
|
||||
|
||||
- Зберігає приватних агентів користувача або команди.
|
||||
- API:
|
||||
- `GET /agents`
|
||||
- `POST /agents`
|
||||
- Для MVP:
|
||||
- один агент «Team Assistant»
|
||||
- мінімальний чат з LLM
|
||||
- Під капотом можна використовувати будь-який зовнішній LLM API.
|
||||
|
||||
### 3.8. Search Service
|
||||
|
||||
- На базі Meilisearch.
|
||||
- API:
|
||||
- `GET /search?q=...&scope=messages|docs|tasks`
|
||||
- MVP:
|
||||
- індексація публічних повідомлень + задач.
|
||||
|
||||
## 4. Дані та моделі
|
||||
|
||||
### 4.1. База даних (PostgreSQL)
|
||||
|
||||
Згідно з Data Model & Event Catalog:
|
||||
|
||||
- `users`
|
||||
- `teams`, `team_members`
|
||||
- `channels`, `messages`, `reactions`
|
||||
- `followups`
|
||||
- `projects`, `tasks`
|
||||
- `agents`, `agent_runs`
|
||||
- `files`
|
||||
- `audit_log`
|
||||
- мінімальні індекси для пошуку повідомлень
|
||||
|
||||
**ID формати:** `ulid` або `ksuid` (обов'язково глобально унікальні).
|
||||
|
||||
### 4.2. Message Bus (NATS JetStream)
|
||||
|
||||
Використовується не на всіх етапах MVP, але:
|
||||
|
||||
- дозволяє публікувати події:
|
||||
- `message.created`
|
||||
- `followup.created`
|
||||
- `task.created`
|
||||
- забезпечує надійний outbox pattern.
|
||||
|
||||
### 4.3. Пошукові індекси (Meilisearch)
|
||||
|
||||
Структури документів:
|
||||
|
||||
- **Messages**: id, team_id, channel_id, created_at, body_plain (якщо public)
|
||||
- **Tasks**: id, project_id, title, status, priority, labels
|
||||
- **Docs** (можна не включати в MVP)
|
||||
|
||||
## 5. WebSockets
|
||||
|
||||
- Створений окремий WS endpoint.
|
||||
- Події які обробляє фронт:
|
||||
- нове повідомлення
|
||||
- оновлення повідомлення
|
||||
- реакція
|
||||
- В MVP достатньо канального namespace:
|
||||
- `/ws/channels/{id}`
|
||||
|
||||
## 6. Приватність та режими (Public / Confidential)
|
||||
|
||||
### Public Mode
|
||||
|
||||
- Канал доступний гостям на `/c/:slug`.
|
||||
- Повідомлення індексуються у Meilisearch.
|
||||
- Дані зберігаються у `messages.body_plain`.
|
||||
|
||||
### Confidential Mode
|
||||
|
||||
- Повідомлення зберігаються як `body_enc` + `key_id`.
|
||||
- Клієнт розшифровує.
|
||||
- Не індексується, не надсилається в Meili.
|
||||
- Всі вкладення — шифротекст із pre-signed URL.
|
||||
- На фронті потрібно використовувати **E2EE-хелпери** (поза scope MVP — stub OK).
|
||||
|
||||
## 7. API взаємодія (загальні правила)
|
||||
|
||||
- Усі виклики захищені Bearer JWT.
|
||||
- Потрібно використовувати typed API-клієнт (можна автогенерувати зі спрощеної OpenAPI).
|
||||
- Обробка помилок:
|
||||
- 400 → помилка користувача
|
||||
- 403 → access denied
|
||||
- 404 → ресурс не знайдено
|
||||
- 429 → rate limit
|
||||
- 500 → системна помилка
|
||||
|
||||
## 8. Front-End архітектура
|
||||
|
||||
### 8.1. Каталоги
|
||||
|
||||
```
|
||||
src/
|
||||
api/
|
||||
components/
|
||||
features/
|
||||
onboarding/
|
||||
auth/
|
||||
chat/
|
||||
channels/
|
||||
followups/
|
||||
projects/
|
||||
agents/
|
||||
hooks/
|
||||
layout/
|
||||
routes/
|
||||
store/
|
||||
styles/
|
||||
```
|
||||
|
||||
### 8.2. Рекомендовані патерни
|
||||
|
||||
- React Query для запитів і кешу.
|
||||
- Zustand або Context для глобального стану онбордингу.
|
||||
- Мовна локалізація через простий i18n dictionary.
|
||||
- ErrorBoundary на рівні layout.
|
||||
|
||||
## 9. MVP Нефункціональні очікування
|
||||
|
||||
- Латентність чатів ≤ 300 мс (без LLM).
|
||||
- Одночасно 10–50 активних користувачів.
|
||||
- Стабільна робота мобільної версії (мінімально).
|
||||
- Стійкий логін, без циклів і моклих лінків.
|
||||
|
||||
## 10. Для Cursor
|
||||
|
||||
Цей документ дає базу для:
|
||||
|
||||
- генерації React-компонентів,
|
||||
- створення нового маршруту `/onboarding`,
|
||||
- реалізації каналів і чатів,
|
||||
- інтеграції базового агента,
|
||||
- роботи з API без необхідності читати всю специфікацію.
|
||||
Reference in New Issue
Block a user