# 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 без необхідності читати всю специфікацію.