# 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`) in workspaces or **books**, icon + cover,
  ordering, TipTap rich-text with **tables + checklists**, stored as JSON + HTML.
- **Books** 📚 — Independent containers for pages, collapsible in the sidebar.
- **Tasks** ✅ — Kanban (todo/doing/doing→done), priorities, deadlines, **assignees**,
  links to books/pages, **per-team boards**.
- **Teams** 👥 — Teams with managers/members, **own workspaces** (`TEAM_"name"` badge),
  permission **groups** (e.g. Team Creators: teams.create/edit/invite, workspace.invite).
- **Invites + notifications** 🔔 — Pending invites with accept/decline, bell with unread
  badge (polling + realtime push), notifications for invites and chat messages.
- **Team chat** 💬 — Realtime workspace channel via Socket.IO.
- **Uploads** 📤 — Avatar/background images uploadable (served from `/uploads`).
- **Calendar** 🗓️ — Deadlines from tasks appear automatically.
- **Time tracking** ⏱️ — Top-right timer, entries linkable to books, history list.
- **Settings window** ⚙️ — Profile (name, email, avatar, password), appearance
  (light/dark/system), language (**Deutsch, English, 中文**), background image + blur.
- **Admin dashboard** 🛡️ — Stats, user management (admin flag, delete).
- **User discovery** 🔎 — Fuzzy search to find and invite collaborators.
- **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
```

Open the frontend: on first start a **web installer** guides you through creating the
admin account and your first workspace. Afterwards the team registers via the UI
and joins workspaces by email invite (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).