# yashh0225/codecollab architecture

> Architecture diagram of the GitHub repository yashh0225/codecollab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yashh0225/codecollab
- Repository: https://github.com/yashh0225/codecollab

## Overview

1. **What this repo is**
   - CodeCollab is a split-system collaborative code editor: a browser client, a REST API, and a dedicated real-time sync server.
   - The core architectural idea is that code editing state is not managed by the REST server; it is managed by Yjs CRDT documents relayed over WebSockets.

2. **Client boundary: React + Vite editor app**
   - `client/src` is the browser application built with React/Vite.
   - `App.jsx` and `pages/` provide routing for the landing page, room page, and OAuth callback.
   - The main user-facing editing surface is `components/Editor.jsx`, backed by Monaco Editor and Yjs bindings.

3. **Editor subsystem**
   - `Editor.jsx`, `Toolbar.jsx`, `Sidebar.jsx`, `StatusBar.jsx`, and `HistoryPanel.jsx` form the in-room UI.
   - The editor binds Monaco to Yjs; the toolbar handles room/language actions; the sidebar shows room and collaborators; the status bar shows cursor and connection info.
   - History is surfaced as saved snapshots, but restoring a snapshot still pushes a normal collaborative document change through Yjs.

4. **Client state/sync hooks**
   - `hooks/useYjs.js` initializes the Yjs document and connects the browser to the WebSocket sync layer.
   - `hooks/useAwareness.js` handles ephemeral presence data such as usernames, cursor positions, and colors.
   - These hooks are the boundary between the React UI and the real-time collaboration protocol.

5. **REST API boundary: Express server**
   - `server/index.js` is the HTTP API entry point.
   - `routes/auth.js` handles registration, login, JWT issuance, and OAuth flows for Google/GitHub.
   - `routes/rooms.js` handles room creation, room lookup, and snapshot history.
   - `middleware/auth.js` gates protected endpoints using JWT verification.

6. **Persistence and relational data**
   - PostgreSQL is the durable store for users, rooms, and snapshots, as described in the schema in the README.
   - The database is accessed from `server/db.js`; the README also describes a demo/in-memory fallback when Supabase credentials are absent.
   - This means user identity and historical room metadata live separately from live document sync state.

7. **Real-time sync boundary: dedicated Yjs websocket server**
   - `sync-server/server.js` is a separate Node process using `y-websocket`.
   - Its role is intentionally narrow: accept Yjs binary updates, broadcast them to room peers, and maintain room membership.
   - It does not interpret code syntax or application semantics; it only moves CRDT updates.

8. **Document persistence for live collaboration**
   - `sync-server/persistence.js` stores and reloads Yjs document state in Redis.
   - The README describes Redis as the fast persistence/cache layer for serialized Y.Doc state, so new clients can hydrate a room quickly without replaying full edit history.
   - This is the persistence layer for live editor content, distinct from PostgreSQL snapshots.

9. **Awareness/presence is separate from document data**
   - Cursor position, user names, and collaborator colors are carried through Yjs awareness, not the document itself.
   - These values are ephemeral: they drive live UI like colored cursors and online user lists, but they are not meant to be persisted across disconnects.

10. **Primary data flows**
   - **Auth flow:** browser → Express `/auth/*` → PostgreSQL/Supabase → JWT returned to client.
   - **Room flow:** browser → Express `/rooms` → PostgreSQL room record → client navigates to room page.
   - **Edit flow:** Monaco input → Yjs document in browser → WebSocket sync server → other clients’ Yjs docs → Monaco re-renders.
   - **Presence flow:** browser awareness state → sync server relay → sidebar/cursor UI updates.
   - **History flow:** client requests/creates snapshot via Express → PostgreSQL snapshot row; restoring a snapshot updates the Yjs document and propagates like any other edit.

11. **Deployment/runtime separation**
   - The architecture is explicitly three runnable services: client on Vercel, REST API on Render, and WebSocket sync on Railway.
   - External managed services are used for state: Supabase PostgreSQL and Upstash Redis.
   - This separation matters: HTTP auth/CRUD, live collaboration, and persistence each scale and fail independently.

12. **What to draw in an architecture diagram**
   - Show the browser client as one box with Monaco/Yjs/UI components inside.
   - Show the Express API as a separate box connected to PostgreSQL.
   - Show the Yjs WebSocket server as a separate box connected to Redis and to all browsers.
   - Treat presence as an overlay on the WebSocket path, and treat snapshots as a relational side channel through the REST API.

Main entry points: [`client/src/components/Editor.jsx`](https://github.com/yashh0225/codecollab/blob/main/client/src/components/Editor.jsx) (Editor), [`server/routes/rooms.js`](https://github.com/yashh0225/codecollab/blob/main/server/routes/rooms.js) (Room routes), [`client/src/pages`](https://github.com/yashh0225/codecollab/tree/main/client/src/pages) (Pages), [`server/index.js`](https://github.com/yashh0225/codecollab/blob/main/server/index.js) (Express server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser client"]
  node_client_app["App shell<br/>react entry<br/>[App.jsx]"]
  node_client_pages["Pages<br/>route views"]
  node_client_editor["Editor<br/>collab UI<br/>[Editor.jsx]"]
  node_client_toolbar["Toolbar<br/>editor controls<br/>[Toolbar.jsx]"]
  node_client_sidebar["Sidebar<br/>presence panel<br/>[Sidebar.jsx]"]
  node_client_status["Status bar<br/>connection UI<br/>[StatusBar.jsx]"]
  node_client_history["History panel<br/>snapshot UI<br/>[HistoryPanel.jsx]"]
  node_client_yjs{{"Yjs hook<br/>sync hook<br/>[useYjs.js]"}}
  node_client_awareness{{"Awareness hook<br/>presence hook<br/>[useAwareness.js]"}}
  node_client_api["API client<br/>http client<br/>[api.js]"]
end

subgraph group_api["REST API"]
  node_api_server["Express server<br/>http api<br/>[index.js]"]
  node_api_auth["Auth routes<br/>auth endpoints<br/>[auth.js]"]
  node_api_rooms["Room routes<br/>room endpoints<br/>[rooms.js]"]
  node_api_middleware{{"JWT guard<br/>auth middleware<br/>[auth.js]"}}
  node_api_db["DB access<br/>database client<br/>[db.js]"]
end

subgraph group_sync["Realtime sync"]
  node_sync_server["Yjs server<br/>websocket sync<br/>[server.js]"]
  node_sync_persistence["Persistence<br/>ydoc cache<br/>[persistence.js]"]
end

subgraph group_data["Data stores"]
  node_postgres[("PostgreSQL<br/>relational store")]
  node_redis[("Redis<br/>document cache")]
end

node_client_app -->|"routes"| node_client_pages
node_client_pages -->|"room view"| node_client_editor
node_client_editor -->|"controls"| node_client_toolbar
node_client_editor -->|"collaborators"| node_client_sidebar
node_client_editor -->|"status"| node_client_status
node_client_editor -->|"history"| node_client_history
node_client_editor -->|"binds"| node_client_yjs
node_client_sidebar -->|"presence"| node_client_awareness
node_client_status -->|"presence"| node_client_awareness
node_client_yjs -->|"ws updates"| node_sync_server
node_client_awareness -->|"awareness"| node_sync_server
node_client_api -->|"http"| node_api_server
node_api_server -->|"mounts"| node_api_auth
node_api_server -->|"mounts"| node_api_rooms
node_api_auth -->|"protects"| node_api_middleware
node_api_rooms -->|"protects"| node_api_middleware
node_api_auth -->|"reads/writes"| node_api_db
node_api_rooms -->|"reads/writes"| node_api_db
node_api_db -->|"sql"| node_postgres
node_sync_server -->|"state"| node_sync_persistence
node_sync_persistence -->|"cache"| node_redis
node_client_history -.->|"snapshots"| node_api_rooms
node_client_pages -.->|"auth/rooms"| node_client_api

click node_client_app "https://github.com/yashh0225/codecollab/blob/main/client/src/App.jsx"
click node_client_pages "https://github.com/yashh0225/codecollab/tree/main/client/src/pages"
click node_client_editor "https://github.com/yashh0225/codecollab/blob/main/client/src/components/Editor.jsx"
click node_client_toolbar "https://github.com/yashh0225/codecollab/blob/main/client/src/components/Toolbar.jsx"
click node_client_sidebar "https://github.com/yashh0225/codecollab/blob/main/client/src/components/Sidebar.jsx"
click node_client_status "https://github.com/yashh0225/codecollab/blob/main/client/src/components/StatusBar.jsx"
click node_client_history "https://github.com/yashh0225/codecollab/blob/main/client/src/components/HistoryPanel.jsx"
click node_client_yjs "https://github.com/yashh0225/codecollab/blob/main/client/src/hooks/useYjs.js"
click node_client_awareness "https://github.com/yashh0225/codecollab/blob/main/client/src/hooks/useAwareness.js"
click node_client_api "https://github.com/yashh0225/codecollab/blob/main/client/src/services/api.js"
click node_api_server "https://github.com/yashh0225/codecollab/blob/main/server/index.js"
click node_api_auth "https://github.com/yashh0225/codecollab/blob/main/server/routes/auth.js"
click node_api_rooms "https://github.com/yashh0225/codecollab/blob/main/server/routes/rooms.js"
click node_api_middleware "https://github.com/yashh0225/codecollab/blob/main/server/middleware/auth.js"
click node_api_db "https://github.com/yashh0225/codecollab/blob/main/server/db.js"
click node_sync_server "https://github.com/yashh0225/codecollab/blob/main/sync-server/server.js"
click node_sync_persistence "https://github.com/yashh0225/codecollab/blob/main/sync-server/persistence.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_app,node_client_pages,node_client_editor,node_client_toolbar,node_client_sidebar,node_client_status,node_client_history,node_client_yjs,node_client_awareness,node_client_api toneBlue
class node_api_server,node_api_auth,node_api_rooms,node_api_middleware,node_api_db toneAmber
class node_sync_server,node_sync_persistence toneMint
class node_postgres,node_redis toneRose
```

## Components

### Browser client

React/Vite app for the collaborative editor UI and room navigation.

- [App shell](https://github.com/yashh0225/codecollab/blob/main/client/src/App.jsx): react entry · Top-level client bootstrap and routing container. · `client/src/App.jsx`
- [Pages](https://github.com/yashh0225/codecollab/tree/main/client/src/pages): route views · Landing, room, and auth callback screens. · `client/src/pages`
- [Editor](https://github.com/yashh0225/codecollab/blob/main/client/src/components/Editor.jsx): collab UI · Main in-room editing surface and collaboration controls. · `client/src/components/Editor.jsx`
- [Toolbar](https://github.com/yashh0225/codecollab/blob/main/client/src/components/Toolbar.jsx): editor controls · Room and language actions for the editor room. · `client/src/components/Toolbar.jsx`
- [Sidebar](https://github.com/yashh0225/codecollab/blob/main/client/src/components/Sidebar.jsx): presence panel · Room info and collaborator list UI. · `client/src/components/Sidebar.jsx`
- [Status bar](https://github.com/yashh0225/codecollab/blob/main/client/src/components/StatusBar.jsx): connection UI · Cursor, connection, and runtime status display. · `client/src/components/StatusBar.jsx`
- [History panel](https://github.com/yashh0225/codecollab/blob/main/client/src/components/HistoryPanel.jsx): snapshot UI · Saved snapshot history and restore actions. · `client/src/components/HistoryPanel.jsx`
- [Yjs hook](https://github.com/yashh0225/codecollab/blob/main/client/src/hooks/useYjs.js): sync hook · Initializes the shared Yjs document and websocket connection. · `client/src/hooks/useYjs.js`
- [Awareness hook](https://github.com/yashh0225/codecollab/blob/main/client/src/hooks/useAwareness.js): presence hook · Manages ephemeral usernames, cursors, and colors. · `client/src/hooks/useAwareness.js`
- [API client](https://github.com/yashh0225/codecollab/blob/main/client/src/services/api.js): http client · Browser-side REST calls for auth and room operations. · `client/src/services/api.js`

### REST API

Express HTTP service for auth, rooms, and snapshots.

- [Express server](https://github.com/yashh0225/codecollab/blob/main/server/index.js): http api · REST entry point for authentication and room metadata. · `server/index.js`
- [Auth routes](https://github.com/yashh0225/codecollab/blob/main/server/routes/auth.js): auth endpoints · Registration, login, JWT issuance, and OAuth flows. · `server/routes/auth.js`
- [Room routes](https://github.com/yashh0225/codecollab/blob/main/server/routes/rooms.js): room endpoints · Room creation, lookup, and snapshot history APIs. · `server/routes/rooms.js`
- [JWT guard](https://github.com/yashh0225/codecollab/blob/main/server/middleware/auth.js): auth middleware · Protects private endpoints with JWT verification. · `server/middleware/auth.js`
- [DB access](https://github.com/yashh0225/codecollab/blob/main/server/db.js): database client · Server-side database access layer. · `server/db.js`

### Realtime sync

Dedicated Yjs websocket process for document replication and presence.

- [Yjs server](https://github.com/yashh0225/codecollab/blob/main/sync-server/server.js): websocket sync · Dedicated websocket process that relays Yjs updates. · `sync-server/server.js`
- [Persistence](https://github.com/yashh0225/codecollab/blob/main/sync-server/persistence.js): ydoc cache · Loads and stores serialized Y.Doc state for fast room hydration. · `sync-server/persistence.js`

### Data stores

Durable and fast persistence layers used by the split backend.

- **PostgreSQL**: relational store · Durable store for users, rooms, and snapshots.
- **Redis**: document cache · Fast persistence layer for live Yjs document state.

## Connections

- App shell → Pages: routes · App renders the main page views.
- Pages → Editor: room view · Room page mounts the collaborative editor.
- Editor → Toolbar: controls · Editor UI includes room and language actions.
- Editor → Sidebar: collaborators · Editor shell exposes collaborator and room context.
- Editor → Status bar: status · Editor shell shows cursor and connection status.
- Editor → History panel: history · Editor shell surfaces snapshot history.
- Editor → Yjs hook: binds · Editor is driven by the shared Yjs document.
- Sidebar → Awareness hook: presence · Sidebar consumes awareness state for online users.
- Status bar → Awareness hook: presence · Status UI reflects ephemeral collaboration state.
- Yjs hook → Yjs server: ws updates · Browser document syncs edits over websockets.
- Awareness hook → Yjs server: awareness · Presence updates are relayed through the sync server.
- API client → Express server: http · Client talks to the REST API for auth and rooms.
- Express server → Auth routes: mounts · Express mounts authentication routes.
- Express server → Room routes: mounts · Express mounts room and snapshot routes.
- Auth routes → JWT guard: protects · JWT guard secures private auth-adjacent actions.
- Room routes → JWT guard: protects · JWT guard secures room operations.
- Auth routes → DB access: reads/writes · Auth flow persists users and tokens metadata.
- Room routes → DB access: reads/writes · Room and snapshot metadata is stored relationally.
- DB access → PostgreSQL: sql · Server persistence uses PostgreSQL as the durable store.
- Yjs server → Persistence: state · Sync server loads and stores document state.
- Persistence → Redis: cache · Serialized Yjs documents are cached in Redis.
- History panel → Room routes: snapshots · History UI fetches and restores snapshot records via REST.
- Pages → API client: auth/rooms · Pages initiate login, callback handling, and room creation flows.