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