Cloud Codex

``` ____ _ _ ____ _ / ___| | ___ _ _ __| | / ___|___ __| | _____ __ | | | |/ _ \| | | |/ _` | | | / _ \ / _` |/ _ \ \/ / | |___| | (_) | |_| | (_| | | |___| (_) | (_| | __/> < \____|_|\___/ \__,_|\__,_| \____\___/ \__,_|\___/_/\_\ ```

Real-time team docs that you actually own.

A self-hosted, real-time collaborative documentation platform by Cloud City Computing, LLC

CI Release Tests Coverage (lines) Node License

> **A self-hosted Confluence/Notion alternative built on real CRDT > collaboration, with GitHub as a first-class surface — not a plugin.** > Multiple users edit the same document at the same time with conflict-free > merging, browse and edit a linked GitHub repo without leaving the page, > and run the whole stack on one box with one Node container and one MySQL > container. --- ## What it looks like One document, two people, two browsers. `alice` owns the squad and `bob` is a member of it; both are in the editor at the same time, and each sees the other's presence marker next to the document title. ![Two users editing the same Cloud Codex document at the same time, each showing both presence avatars](docs/images/collaborative-editing.png) Browse and full-text search across everything you can reach, and a document with its page tree, version, inline comments and export options.

Browsing and searching documents in Cloud Codex A Cloud Codex document with its page tree and version history

--- ## Why Cloud Codex **True real-time editing, not last-write-wins.** Every doc is a Yjs CRDT. Two people typing in the same paragraph see each other's cursors, and the merge is automatic — there's no "your version overwrote mine" moment. The same WebSocket carries comments and presence, so the doc feels alive while you work in it. **GitHub built in, not bolted on.** Browse a repo's file tree, edit files in-browser with proper commits, open and review pull requests, embed code or issues directly into a doc, and link a doc to a GitHub file for two-way push/pull sync. No webhooks, no background sync — every GitHub call is live, scoped to the user's own OAuth token (encrypted at rest with AES-256-GCM). **Layered access that composes.** Workspaces own squads, squads own archives, archives own documents. Permissions cascade through a 7-step resolution that runs in one SQL fragment — admin → archive grants → creator → workspace owner → squad role → squad grants → workspace flag. Share a single doc with one person, a whole squad, or every member of the workspace, without restructuring your org. **Self-host on one box.** One Node process runs the API, both WebSocket servers, and the prod-built frontend. One MySQL container holds the data. No message broker, no Redis, no Elasticsearch, no external job queue. `docker compose up -d` and you're running. --- ## How it compares | | Cloud Codex | Notion | Confluence | Outline | |------------------------------------------------|-------------|--------------|---------------|---------------| | Self-hosted, no SaaS dependency | ✓ | ✗ | self-host paid | ✓ | | True real-time CRDT collaboration | ✓ | ✓ | ✗ | partial | | GitHub repo browse + in-browser edit + PR | ✓ | ✗ | plugin | ✗ | | Inline code/issue embeds with pinned refs | ✓ | partial | ✗ | ✗ | | Inline comments with tags + status workflow | ✓ | partial | ✓ | partial | | Invite-only registration by default | ✓ | mixed | ✓ | ✓ | | Single Docker bring-up | ✓ | n/a | ✗ | ✓ | | Source-available, view & modify the code | ✓ | ✗ | ✗ | ✓ | Honest framing: Cloud Codex is opinionated and lean. If you need a public-facing wiki, anonymous read access, or SSO beyond Google Workspace domain-restriction, this isn't for you. If you want a self-hosted spot for a working team to actually write together, it probably is. --- ## Highlights ``` ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ CLOUD CODEX ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ │ ┌───────────┬──────────────┬────┴──────┬───────────┬────────────────┐ │ │ │ │ │ │ real-time GitHub layered comments notifications self-host CRDT 1st-class access tagged coalesced in one box cursors + repo edit + 7-step + threaded inbox + email single Node presence PRs + embeds cascade + status opt-in per type process ``` - **Edit together, conflict-free** — Yjs CRDT, remote cursors, live presence avatars, doc-keyed WebSocket - **GitHub, not bolted on** — repo tree, in-browser edit, branch + PR management, code/issue/PR embeds, doc↔file sync, CI status inline - **Layered access that composes** — 7-step resolution at the SQL fragment level, no per-step round trips - **Talk back to the doc** — text-anchored comments with tags (comment / suggestion / question / issue / note) and status workflow (open → resolved / dismissed), threaded replies, real-time WS broadcast - **Notifications that don't spam** — 60-second coalescing window, per-type email opt-in/out, push-only `/notifications-ws` channel, defaults that favor signal over noise - **Own your destiny** — invite-only, no telemetry, no third-party services in the request path, source-available, runs on your box → Full feature reference in [docs/features.md](docs/features.md). --- ## Architecture at a glance ``` ┌────────────────────────────────────────────────────────────────┐ │ Browser (single-page app) │ │ React 19 + Tiptap + Yjs · bundled by Vite │ └─────────┬─────────────────┬─────────────────┬─────────────────┘ │ HTTP / JSON │ WS /collab │ WS /notifications-ws │ │ │ ┌─────────▼─────────────────▼─────────────────▼─────────────────┐ │ Node.js (single process) │ │ Express + 18 routers · 2 WebSocket servers │ │ Notifications funnel · Yjs CRDT sync · GitHub proxy │ └──────────────────────────┬─────────────────────────────────────┘ │ mysql2 pool (10) ┌──────────────────────────▼─────────────────────────────────────┐ │ MySQL 8 (Docker) │ │ 25 tables · FULLTEXT search · activity log auto-prune │ └────────────────────────────────────────────────────────────────┘ ``` → Full system design and decisions in [docs/architecture.md](docs/architecture.md). --- ## Quick start **Try a release.** Pulls a prebuilt image, so this needs Docker and nothing else. No Node, no build step. ```bash git clone https://github.com/Cloud-City-Computing/c2.git cd c2 cp .env.example .env # fill in DB and admin credentials and APP_URL; SMTP is optional docker compose -f docker-compose-release.yml up -d docker compose -f docker-compose-release.yml run --rm app npm run migrate -- --adopt-fresh-install ``` The last line is a one-time step on a fresh install: it records that the schema `init.sql` just built already has every migration. Until it runs, `/readyz` answers 503 `migrations` and Docker reports the container unhealthy. `APP_URL` is the address people use to reach the instance; production refuses to start without it, and invitation and password-reset links are built from it. **Work on the source.** Installs dependencies and runs the dev server with hot reload. ```bash git clone https://github.com/Cloud-City-Computing/c2.git cd c2 cp .env.example .env # fill in DB and admin credentials; SMTP is optional ./start.sh # installs deps, starts MySQL, launches dev server ``` Without SMTP the server still starts. Invitations then show a link to copy instead of being emailed, and password reset, email two-factor codes and notification emails are unavailable until you configure it. The application will be available at **http://localhost:3000**. If something else already owns that port, set `PORT` in `.env` and update `APP_URL` to match, since invitation and password-reset links are built from `APP_URL`. → Full setup in [docs/getting-started.md](docs/getting-started.md). --- ## Documentation Start with these and the rest flows from there: - **[Getting Started](docs/getting-started.md)** — local setup, env vars, scripts, seed data - **[Architecture](docs/architecture.md)** — system design, project structure, full tech stack - **[Features](docs/features.md)** — every major capability - **[Security](docs/security.md)** — defense-in-depth model - **[Full doc index](docs/README.md)** — every reference, every API doc --- ## Roadmap Roadmap and known issues live in **GitHub Issues** — see open [issues](https://github.com/RhykerWells/c2/issues) and milestones. --- ## Contributing Contributions are welcome. The bar is low: read [CONTRIBUTING.md](CONTRIBUTING.md), match the existing style, lint and test must pass, and the change should explain its **why** in the PR description. See [CLAUDE.md](CLAUDE.md) for the long-form conventions that govern this codebase. --- ## Security Please report vulnerabilities privately. See [SECURITY.md](SECURITY.md) for the disclosure policy and contact address. Don't open a public issue for an unfixed vulnerability. --- ## License Cloud Codex is released under a **source-available license**. You may view, modify, and self-host the software for personal, educational, or internal business use at no cost. Commercial use as a hosted service requires a separate license from [Cloud City Computing, LLC](https://cloudcitycomputing.com). See [LICENSE](LICENSE) for full terms.