A real-time collaborative documentation platform by Cloud City Computing, LLC
``` ┌──────────────────────────────┐ │ Start Here │ └─────────┬─────────┬──────────┘ │ │ ▼ ▼ getting- architecture started │ │ └────┬────┘ │ ┌──────────┼──────────────────────────────────┐ ▼ ▼ ▼ ▼ features access-control security deployment │ │ │ │ └─► testing │ │ │ ▼ ▼ services / notifications troubleshooting │ ▼ frontend │ ▼ ┌──────────────────────────────────────────────────┐ │ API Reference │ │ auth · workspaces-squads-archives │ │ documents · comments · search-favorites │ │ notifications · activity-watches │ │ admin · oauth-github │ └──────────────────────────────────────────────────┘ ``` ## Start Here → **[Getting Started](./getting-started.md)** — Prerequisites, environment setup, running the application, and seed data. → **[Sign-in](./sign-in.md)** — Local accounts, Google, and OIDC, with the redirect URIs and provider notes. → **[Architecture Overview](./architecture.md)** — System design, project structure, key design decisions, full tech stack. ## References | Document | Summary | |----------|---------| | [getting-started.md](./getting-started.md) | Prerequisites, setup, environment variables, NPM scripts, Makefile targets, seed data | | [sign-in.md](./sign-in.md) | Local accounts, Google, and OIDC: the redirect URIs, the settings, and provider notes | | [features.md](./features.md) | Detailed descriptions of every feature | | [architecture.md](./architecture.md) | System overview, design decisions, project structure, tech stack | | [database.md](./database.md) | Complete MySQL schema reference — 25 tables, columns, indexes, relationships, migrations list | | [access-control.md](./access-control.md) | Layered access control — 7-priority resolution flowchart | | [services.md](./services.md) | Collab WebSocket, notifications, user-channel WS, email, DB module, middleware | | [notifications.md](./notifications.md) | Notifications subsystem — funnel, coalescing, triggers, preferences | | [frontend.md](./frontend.md) | React app routing, pages, hooks, components, build setup | | [security.md](./security.md) | Defense-in-depth model — auth, sanitization, encryption, headers, rate limiting | | [testing.md](./testing.md) | Two default Vitest projects plus an opt-in live-MySQL one, per-glob coverage thresholds | | [deployment.md](./deployment.md) | Production operations — Docker Compose, TLS, backups, upgrades, logs | | [troubleshooting.md](./troubleshooting.md) | Common setup/runtime failures and the fix for each | ## Specs (`specs/`) Where the maps describe how the system works today, [`specs/`](./specs/README.md) describes what we intend to build next and why. | Document | What it is | |----------|---------| | [specs/roadmap.md](./specs/roadmap.md) | The tracks the project is decomposed into, the evidence behind each, and the order to do them in | | [specs/2026-10-14-standalone-codex.md](./specs/2026-10-14-standalone-codex.md) | The standalone track: Codex becomes a standalone product, the suite integration is removed, toward 1.0 | ## Deep maps (`maps/`) The references above describe the product. [`maps/`](./maps/README.md) describes the **mechanism**: dense, `file:line`-cited maps written for someone about to change the code, covering the wiring, the invariants, and the traps. | Map | Covers | |----------|---------| | [maps/request-lifecycle.md](./maps/request-lifecycle.md) | Boot order, middleware stack, session resolution, WebSocket upgrades, error handling | | [maps/access-control.md](./maps/access-control.md) | The 7-clause SQL fragments, their param contract, and the four secondary permission systems | | [maps/documents-and-collab.md](./maps/documents-and-collab.md) | Dual-state storage, the Yjs protocol, every writer of document content, versions | | [maps/github-integration.md](./maps/github-integration.md) | Token crypto, the 5-state sync machine, embeds, PR sessions, team sync | | [maps/notifications-and-activity.md](./maps/notifications-and-activity.md) | Activity taxonomy, auto-watch, fan-out, the notification funnel, the inbox WebSocket | | [maps/data-model.md](./maps/data-model.md) | All 25 tables, ACL columns, the generated search column, `init.sql` vs `migrations/` | | [maps/frontend-architecture.md](./maps/frontend-architecture.md) | Routes, lazy chunks, the `util.jsx` API layer, hooks, preferences, lint rules | | [maps/build-test-and-ops.md](./maps/build-test-and-ops.md) | Dual-root layout, Docker topologies, the three Vitest projects (one live-MySQL), coverage thresholds, CI | | [maps/open-questions.md](./maps/open-questions.md) | Dead code paths and suspected defects found while writing the maps | ## API Reference | Document | Endpoints covered | |----------|-------------------| | [api/auth.md](./api/auth.md) | Login, signup (invite-only), 2FA, password reset, session management | | [api/workspaces-squads-archives.md](./api/workspaces-squads-archives.md) | Workspaces, squads, squad members, archives, access grants, archive ↔ repo links | | [api/documents.md](./api/documents.md) | Document CRUD, autosave, publish, version history, export (Markdown/DOCX) | | [api/comments.md](./api/comments.md) | Document comments, replies, status, text-selection anchors | | [api/search-favorites.md](./api/search-favorites.md) | Full-text search, browse, favorites | | [api/notifications.md](./api/notifications.md) | Inbox, unread badge, preferences | | [api/activity-watches.md](./api/activity-watches.md) | Workspace activity stream + per-user watches | | [api/admin.md](./api/admin.md) | User/workspace management, invitations, permissions, live presence telemetry, webhook subscriptions | | [api/webhooks.md](./api/webhooks.md) | Outbound events: the signed envelope a webhook receiver gets, and when | | [api/oauth-github.md](./api/oauth-github.md) | Google SSO, GitHub OAuth, 40+ GitHub repo / PR / issue / embed proxy endpoints | ## 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. --- ## ASCII conventions (for contributors) The docs use a consistent ASCII visual style — please match it when adding new content: - **Banners** use a `╔══...══╗` box, max width **78 columns**, with title in caps and a short subtitle below. - **Diagrams** use heavy box-drawing (`┃ ━ ┏ ┛`) for primary flows and light (`│ ─ ┌ ┘`) for secondary structure. Arrows: `▼ ▲ ◀ ▶` for flow, `─►` for lighter pointers. - **API doc banners** use the slim `─── ◆ ───` style instead — the API pages are reference docs and shouldn't carry chrome. - **All ASCII inside fenced code blocks** so GitHub doesn't reflow it. - **No emoji** in ASCII — visual weight comes from box characters and whitespace. - **78-column max width** — keeps everything readable in terminal, GitHub, and IDE markdown previews.