chore: initial repository scaffolding

- Add README with features, quick-start (local + Docker) and docs index - Add MIT LICENSE, root .gitignore and .env.example - Add docker-compose.yml (postgres + backend + frontend) - Add root package.json with install:all/dev helpers - Add Gitea CI workflow (backend syntax check, frontend build)
2026-09-22 13:33:22 +02:00
commit 29c35f506d
7 changed files with 231 additions and 0 deletions
@@ -0,0 +1,104 @@
+# openStack — Collaborative Workspace (Vue 3 + Express + PostgreSQL)
+
+A Notion-like collaborative workspace: rich pages, nested hierarchy, workspaces with
+role-based members, real-time collaboration (Socket.IO), comments, search, and
+light/dark mode. Self-hostable via Node.js or Docker Compose.
+
+> **Status:** Web app MVP (see [`docs/ROADMAP.md`](docs/ROADMAP.md) for desktop clients
+> for Windows / macOS / Linux).
+
+## Features
+
+- **Auth** — Register / login with JWT (access token), bcrypt password hashing.
+- **Workspaces** — Create workspaces, invite members by email (`owner` / `admin` /
+  `member` / `viewer`), change roles, remove members.
+- **Pages** — Nested pages (`parent_id`), icon + cover, ordering, TipTap rich-text
+  content stored as JSON + rendered HTML.
+- **Real-time collaboration** — Socket.IO rooms per page: live content broadcast,
+  presence (who is viewing), typing indicators.
+- **Comments** — Threaded comments per page.
+- **Search** — Full-text search (`ILIKE` on title/content, trigram-ready).
+- **Light / dark mode** — CSS variables + persisted user preference.
+- **Self-hostable** — Documented for bare-metal (`docs/HOSTING.md`) and Docker Compose.
+
+## Monorepo layout
+
+```text
+openStack/
+├── frontend/          # Vue 3 + Vite + Pinia + Vue Router + TipTap
+├── backend/           # Express + Socket.IO + pg (PostgreSQL)
+├── docs/              # SETUP, HOSTING, API, ARCHITECTURE, ROADMAP
+├── docker-compose.yml # postgres + backend + frontend
+├── .env.example       # All required env vars
+└── .gitea/workflows/  # CI (lint + build + test)
+```
+
+## Quick start (development)
+
+Requirements: Node.js 20+, PostgreSQL 14+.
+
+```bash
+# 1. Clone
+git clone https://git.sysdaemon.xyz/x3/openStack.git
+cd openStack
+
+# 2. Configure
+cp .env.example .env
+# edit .env -> DATABASE_URL, JWT_SECRET, ports
+
+# 3. Database
+createdb openstack
+psql openstack < backend/src/db/schema.sql
+
+# 4. Backend
+cd backend && npm install && npm run dev
+# -> http://localhost:3000 (API at /api, health at /api/health)
+
+# 5. Frontend (new terminal)
+cd frontend && npm install && npm run dev
+# -> http://localhost:5173
+```
+
+Default dev flow creates the first user via **Register** in the UI; that user can then
+create workspaces and invite others by email (invited email must have an account).
+
+## Quick start (Docker Compose)
+
+```bash
+cp .env.example .env
+# set POSTGRES_PASSWORD, JWT_SECRET, etc.
+docker compose up --build
+# frontend -> http://localhost:8080
+# backend  -> http://localhost:3000/api/health
+```
+
+See [`docs/HOSTING.md`](docs/HOSTING.md) for production (reverse proxy, TLS, backups).
+
+## Documentation
+
+| Doc | Content |
+|-----|---------|
+| [`docs/SETUP.md`](docs/SETUP.md) | Local dev setup, DB, env vars, troubleshooting |
+| [`docs/HOSTING.md`](docs/HOSTING.md) | Bare-metal hosting + Docker Compose hosting |
+| [`docs/API.md`](docs/API.md) | REST + Socket.IO contract with curl examples |
+| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Data model, auth, realtime design |
+| [`docs/ROADMAP.md`](docs/ROADMAP.md) | Webapp milestones + desktop clients (Win/Mac/Linux binaries via releases) |
+
+## Scripts (root)
+
+```bash
+npm run install:all   # install backend + frontend deps
+npm run dev           # runs backend+frontend concurrently (needs concurrently)
+```
+
+## Security notes
+
+- Passwords hashed with bcrypt (12 rounds). Never stored in plain text.
+- JWT access tokens (default 7d expiry, configurable). Sent as `Authorization: Bearer <token>`.
+- Rate limiting on `/api/auth/*`. Helmet headers enabled. CORS allow-list via `CORS_ORIGIN`.
+- Workspace access enforced server-side on every route (membership check + role check).
+- Socket.IO authenticates via JWT in `auth.token` and re-checks page access on join.
+
+## License
+
+MIT — see [LICENSE](LICENSE).