chore: organize documentation structure for monorepo

- Create /docs structure (microdao, daarion, agents) - Organize 61 cursor technical docs - Add README files for each category - Copy key documents to public categories - Add GitHub setup instructions and scripts
2025-11-15 04:08:35 -08:00
parent 5520665600
commit c552199eed
138 changed files with 39624 additions and 40 deletions
--- a/docs/cursor/27_database_schema_migrations.md
+++ b/docs/cursor/27_database_schema_migrations.md
@@ -0,0 +1,496 @@
+# 27 — Database Schema & Migrations (MicroDAO)
+
+*Повна виробнича специфікація*
+
+---
+
+## 1. Purpose & Scope
+
+Цей документ описує:
+
+- повну схему бази даних microDAO / DAARION.city (всі таблиці);
+- модулі: Messaging, Teams, RBAC, Projects, Docs/Co-Memory, Agents, Wallet, Staking, Payouts, Embassy, Capability System, RWA;
+- порядок міграцій;
+- правила naming-конвенцій;
+- seed-дані для initial bootstrap;
+- інтеграцію з Event Catalog;
+- DevOps pipeline для застосування міграцій (local → staging → prod);
+- rollback policy.
+
+Документ є «джерелом істини» для інженерів.
+
+---
+
+## 2. High-level Structure of the Database
+
+### Домени:
+
+1. Auth / Users
+2. Teams (microDAO ядра)
+3. RBAC & Roles
+4. Channels / Messages / Follow-ups / Co-Memory
+5. Projects / Tasks
+6. Agents / Agent Runs / Tooling
+7. Wallet / Staking / Payouts
+8. RWA (Real-World Assets)
+9. Embassy Module (Webhooks, External Identity, Oracles)
+10. Capability System (Access Keys, Bundles)
+11. Audit & Telemetry
+12. Event Catalog Support (Outbox pattern)
+
+---
+
+## 3. Naming Conventions
+
+### Префікси ID:
+
+- `u_` — user
+- `t_` — team
+- `c_` — channel
+- `m_` — message
+- `f_` — followup
+- `doc_` — document
+- `p_` — project
+- `task_` — task
+- `ag_` — agent
+- `run_` — agent run
+- `ak_` — access key
+- `cap_` — capability
+- `bundle_` — capability bundle
+- `rwa_` — RWA certificate
+- `emb_` — embassy identity
+- `hook_` — webhook
+- `evt_` — outbox event
+
+### Таблиці у snake_case
+
+### Версії міграцій:
+
+`000001_init.sql`, `000002_users_teams.sql`, `000003_rbac.sql` …
+
+---
+
+## 4. Full Schema by Modules
+
+Нижче — структурована схема по розділах.
+
+Це основа для міграцій (варіант C).
+
+---
+
+### 4.1 Users & Auth
+
+```sql
+create table users (
+  id text primary key,           -- u_...
+  email text unique not null,
+  created_at timestamptz default now(),
+  last_login_at timestamptz
+);
+
+create table sessions (
+  session_id text primary key,
+  user_id text references users(id) on delete cascade,
+  created_at timestamptz default now(),
+  expires_at timestamptz
+);
+```
+
+---
+
+### 4.2 Teams / microDAO
+
+```sql
+create table teams (
+  id text primary key,          -- t_...
+  name text not null,
+  slug text unique not null,
+  mode text not null check (mode in ('public','confidential')),
+  created_at timestamptz default now()
+);
+
+create table team_members (
+  team_id text references teams(id) on delete cascade,
+  user_id text references users(id) on delete cascade,
+  role text not null,           -- Owner | Guardian | Member
+  viewer_type text not null,    -- reader | commenter | contributor
+  primary key (team_id, user_id)
+);
+```
+
+---
+
+### 4.3 Channels / Messages / Follow-ups / Co-Memory
+
+```sql
+create table channels (
+  id text primary key,            -- c_...
+  team_id text references teams(id),
+  name text not null,
+  created_at timestamptz default now()
+);
+
+create table messages (
+  id text primary key,           -- m_...
+  channel_id text references channels(id),
+  user_id text references users(id),
+  body text,                     -- plaintext or encrypted
+  created_at timestamptz default now(),
+  metadata jsonb
+);
+
+create table followups (
+  id text primary key,           -- f_...
+  message_id text references messages(id) on delete cascade,
+  type text,                     -- agent/tool/summary...
+  payload jsonb,
+  created_at timestamptz default now()
+);
+
+create table comemory_items (
+  id text primary key,
+  team_id text references teams(id),
+  embeddings vector(1536),
+  summary text,
+  source_message text,
+  created_at timestamptz default now()
+);
+```
+
+---
+
+### 4.4 Projects / Tasks
+
+```sql
+create table projects (
+  id text primary key,              -- p_...
+  team_id text references teams(id),
+  name text not null,
+  created_at timestamptz default now()
+);
+
+create table tasks (
+  id text primary key,              -- task_...
+  project_id text references projects(id),
+  title text not null,
+  status text not null,
+  assignee text references users(id),
+  created_at timestamptz default now()
+);
+```
+
+---
+
+### 4.5 Agents / Tooling
+
+```sql
+create table agents (
+  id text primary key,            -- ag_...
+  team_id text references teams(id),
+  name text,
+  config jsonb,
+  created_at timestamptz default now()
+);
+
+create table agent_runs (
+  id text primary key,            -- run_...
+  agent_id text references agents(id),
+  input jsonb,
+  output jsonb,
+  created_at timestamptz default now(),
+  status text
+);
+```
+
+---
+
+### 4.6 Wallet / Staking / Payouts
+
+```sql
+create table wallets (
+  user_id text primary key references users(id),
+  address text unique
+);
+
+create table staking_ringk (
+  id text primary key,
+  user_id text references users(id),
+  amount numeric not null,
+  lock_until timestamptz,
+  created_at timestamptz default now()
+);
+
+create table payouts (
+  id text primary key,
+  user_id text references users(id),
+  amount numeric,
+  symbol text,                -- KWT, 1T, DAAR…
+  created_at timestamptz default now()
+);
+```
+
+---
+
+### 4.7 RWA (Real-World Assets)
+
+```sql
+create table rwa_inventory (
+  id text primary key,             -- rwa_...
+  team_id text references teams(id),
+  type text,                       -- energy/food/water/etc
+  quantity numeric,
+  metadata jsonb,
+  updated_at timestamptz default now()
+);
+```
+
+---
+
+### 4.8 Embassy Module
+
+```sql
+create table embassy_identities (
+  id text primary key,           -- emb_...
+  external_id text,
+  platform text,                 -- energy_union/greenfood/etc
+  metadata jsonb
+);
+
+create table embassy_webhooks (
+  id text primary key,           -- hook_...
+  platform text,
+  secret text,
+  url text,
+  created_at timestamptz default now()
+);
+
+create table oracles (
+  id text primary key,
+  platform text,
+  payload jsonb,
+  created_at timestamptz default now()
+);
+```
+
+---
+
+### 4.9 Capability System (Access Keys / Bundles)
+
+```sql
+create table access_keys (
+  id text primary key,        -- ak_...
+  subject_kind text not null, -- user/agent/integration/embassy
+  subject_id text not null,
+  team_id text,
+  name text not null,
+  status text not null check (status in ('active','revoked','expired')),
+  created_at timestamptz default now(),
+  expires_at timestamptz,
+  last_used_at timestamptz
+);
+
+create table capabilities (
+  id text primary key,        -- cap_...
+  code text not null unique,
+  description text not null
+);
+
+create table access_key_caps (
+  key_id text references access_keys(id) on delete cascade,
+  cap_id text references capabilities(id) on delete cascade,
+  primary key (key_id, cap_id)
+);
+
+create table bundles (
+  id text primary key,        -- bundle_...
+  name text not null unique,
+  created_at timestamptz default now()
+);
+
+create table bundle_caps (
+  bundle_id text references bundles(id) on delete cascade,
+  cap_id text references capabilities(id) on delete cascade,
+  primary key (bundle_id, cap_id)
+);
+```
+
+---
+
+### 4.10 Audit & Telemetry
+
+```sql
+create table audit_log (
+  id text primary key,
+  user_id text,
+  team_id text,
+  action text,
+  resource_kind text,
+  data jsonb,
+  created_at timestamptz default now()
+);
+```
+
+---
+
+### 4.11 Outbox Events (Event Catalog)
+
+```sql
+create table outbox_events (
+  id text primary key,          -- evt_...
+  topic text not null,
+  payload jsonb not null,
+  created_at timestamptz default now(),
+  processed boolean default false
+);
+```
+
+---
+
+## 5. Migration Order (Critical)
+
+### 000001_init.sql
+
+Users, Sessions.
+
+### 000002_microdao_core.sql
+
+Teams, Members, Channels, Messages, Follow-ups.
+
+### 000003_projects_tasks.sql
+
+Projects, Tasks.
+
+### 000004_agents.sql
+
+Agents, Agent Runs.
+
+### 000005_wallet_staking_payouts.sql
+
+Wallet, Staking, Payouts.
+
+### 000006_rwa.sql
+
+RWA Inventory.
+
+### 000007_embassy.sql
+
+Embassy identities, Webhooks, Oracles.
+
+### 000008_access_keys_capabilities.sql
+
+Access Keys, Capabilities, Bundles.
+
+### 000009_audit_outbox.sql
+
+Audit Log + Outbox Events.
+
+---
+
+## 6. Seed Data
+
+### RBAC Roles
+
+- Owner, Guardian, Member, Visitor.
+
+### Capability bundles
+
+- `bundle.role.Owner`
+- `bundle.role.Guardian`
+- `bundle.role.Member`
+- `bundle.role.Visitor`
+- `bundle.plan.Freemium` / `Casual` / `Premium` / `Platformium`
+
+### Initial capabilities
+
+- `chat.message.send`
+- `chat.message.read`
+- `wallet.balance.view`
+- `wallet.stake.ringk`
+- `router.invoke`
+- `agent.run.invoke`
+- `rwa.inventory.update`
+- `embassy.rwa.claim`
+
+---
+
+## 7. Integration with Event Catalog
+
+Всі важливі сутності пишуть події в `outbox_events`.
+
+Основні topics:
+
+- `chat.message.created`
+- `project.created`
+- `task.created`
+- `agent.run.completed`
+- `staking.locked`
+- `payout.generated`
+- `rwa.inventory.updated`
+- `access_key.created`
+- `access_key.revoked`
+- `audit.event`
+
+---
+
+## 8. Local / Staging / Prod Migration Process
+
+1. `supabase db reset` (local only)
+2. `supabase db push` → локальні міграції
+3. CI запускає `pg_prove` або `pgtap` (опційно)
+4. Staging застосовує ті ж міграції
+5. Prod застосовує з confirm gate
+
+---
+
+## 9. Rollback Policy
+
+- Кожна міграція має `-- down` секцію з DROP TABLE IF EXISTS.
+- Для критичних таблиць rollback дозволено тільки до staging, на prod — лише forward-fix.
+- Outbox events не відкочуються.
+- RWA-поведінка не rollback'иться ніколи.
+
+---
+
+## 10. Завдання для Cursor
+
+```text
+You are a senior backend engineer. Generate SQL migration files based on:
+- 27_database_schema_migrations.md
+- 24_access_keys_capabilities_system.md
+- 02_architecture_basics.md
+- 05_coding_standards.md
+
+Tasks:
+1) Create migration files in order: 000001_init.sql through 000009_audit_outbox.sql
+2) Each migration should include:
+   - CREATE TABLE statements
+   - Indexes for foreign keys and frequently queried columns
+   - Constraints (CHECK, UNIQUE, FOREIGN KEY)
+   - Comments for each table/column
+3) Create seed data SQL file for initial capabilities and bundles
+4) Add rollback (-- down) sections for each migration
+
+Output:
+- list of migration files
+- diff
+- summary
+```
+
+---
+
+## 11. Результат
+
+Після створення цього документа:
+
+- повна схема БД задокументована як «джерело істини»;
+- чіткий порядок міграцій для послідовного застосування;
+- готовність до генерації реальних SQL-файлів (варіант C);
+- інтеграція з Event Catalog через Outbox pattern;
+- чітка політика rollback для безпеки.
+
+---
+
+**Версія:** 1.0  
+**Останнє оновлення:** 2024-11-14
+
+