docs: setup, hosting, API, architecture and roadmap

- SETUP: local dev guide (env vars, DB migrate, backend/frontend, troubleshooting) - HOSTING: bare-metal guide (systemd + Nginx + TLS + backups) and Docker Compose guide (deploy, reverse proxy, updates, backup/restore) - API: REST contract with curl examples and Socket.IO event protocol - ARCHITECTURE: stack, data model, auth model, realtime design, theming - ROADMAP: webapp MVP/next steps plus Tauri desktop clients for Windows, macOS and Linux with release-binary plan
2026-09-22 13:33:22 +02:00
parent 5252e3ab4f
commit a407a1381a
5 changed files with 413 additions and 0 deletions
@@ -0,0 +1,77 @@
+# API Reference
+
+Base URL: `http://localhost:3000/api`. Auth: `Authorization: Bearer <jwt>`.
+
+## Auth
+
+### POST /auth/register
+```json
+{ "email": "a@example.com", "name": "Ada", "password": "secret123" }
+```
+-> `201 { user, token }`. Errors: `400` validation, `409` email taken.
+
+### POST /auth/login
+```json
+{ "email": "a@example.com", "password": "secret123" }
+```
+-> `200 { user, token }`. Errors: `401` invalid credentials.
+
+### GET /auth/me
+-> `200 { user }`.
+
+```bash
+curl -X POST localhost:3000/api/auth/register \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"a@example.com","name":"Ada","password":"secret123"}'
+```
+
+## Workspaces
+
+| Method | Path | Role | Description |
+|--------|------|------|-------------|
+| GET | `/workspaces` | member | List my workspaces |
+| POST | `/workspaces` | any logged-in | Create workspace (caller becomes owner) |
+| GET | `/workspaces/:id` | viewer+ | Get workspace |
+| PATCH | `/workspaces/:id` | admin+ | Rename |
+| DELETE | `/workspaces/:id` | owner | Delete |
+| GET | `/workspaces/:id/members` | viewer+ | List members |
+| POST | `/workspaces/:id/members` | admin+ | Invite `{email, role}` (role: admin/member/viewer) |
+| PATCH | `/workspaces/:id/members/:userId` | admin+ | Change role |
+| DELETE | `/workspaces/:id/members/:userId` | admin+ | Remove member |
+
+Roles rank: `viewer < member < admin < owner`. Viewers read only.
+
+## Pages
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/pages/by-workspace/:workspaceId` | List pages (flat, client builds tree) |
+| POST | `/pages` | Create `{workspace_id, parent_id?, title?}` (member+) |
+| GET | `/pages/:id` | Get page + comments |
+| PATCH | `/pages/:id` | Update title/icon/cover/content/position/parent/archive (member+) |
+| DELETE | `/pages/:id` | Delete incl. children via FK cascade |
+| GET | `/pages/search/query?q=&workspace_id=` | Title search |
+| POST | `/pages/:id/comments` | Add comment `{body}` |
+| DELETE | `/pages/:pageId/comments/:commentId` | Delete (author or admin+) |
+
+Content fields: `content_json` (TipTap JSON), `content_html` (rendered HTML).
+
+## Users
+
+- `GET /users/search?email=` — lookup for invites (auth required).
+
+## Health
+
+- `GET /health` -> `{ok:true, db:'up'}` or `503 {ok:false, db:'down'}`.
+
+## Real-time (Socket.IO)
+
+Connect: `io(url, { auth: { token } })`.
+
+- `page:join { pageId }` — join room; server checks workspace membership.
+- `page:edit { pageId, content_json, content_html }` — persist + broadcast to others.
+  Viewers are ignored server-side.
+- `typing { pageId, name }` — broadcast typing indicator.
+- Server events: `page:updated { page, from? }`, `page:deleted { id }`,
+  `comment:added { comment }`, `presence:update { members: [{userId,email,name}] }`,
+  `error:message { error }`.