CodeX - Code Collaboration Platform

CodeX is an online code collaboration platform that enables real-time coding, cursor sharing, live UI preview, and video communication with integrated Git support—no sign-up required.

✨ Try now at codex.dulapahv.dev

This project is part of the course "COMPSCI4025P Level 4 Individual Project" at the University of Glasgow.

For detailed usage instructions and feature documentation, please see the User Manual.

Features

• Real-time Collaboration - Code together in real-time with cursor sharing, highlighting, and follow mode
• Shared Terminal - Execute code and see results together with over 80 supported languages
• Live Preview - Preview UI changes instantly with loaded libraries like Tailwind CSS, and more
• GitHub Integrated - Save your work and open files from your repositories
• Shared Notepad - Take notes together in real-time with rich text and markdown support
• Video, Voice & Screen Sharing - Communicate with your team using video and voice chat, and share your screen

Table of Contents

• Features
• Table of Contents
• Project Structure
• Prerequisites
• Getting Started
• Development
• Test
  • Frontend Test
  • Backend Test
• Build
• Deployment
• Scripts
• Tech Stack
• Coding Style
• Contributing
• User Manual
• License

Project Structure

The project is organized as a monorepo using Turborepo:

CodeX
├── apps/                   # Application packages
│   ├── client/             # Frontend Next.js application
│   │   ├── public/         # Static assets
│   │   ├── src/            # Source code
│   │   │   ├── app/        # Next.js app router pages and API routes
│   │   │   ├── components/ # React components
│   │   │   ├── hooks/      # Custom React hooks
│   │   │   └── lib/        # Utility functions and services
│   │   └── tests/          # Frontend tests (Playwright)
│   └── server/             # Realtime server (Cloudflare Worker with a Durable Object per room)
│       ├── src/            # Source code
│       │   └── utils/      # Utility functions
│       └── tests/          # Backend tests (Jest)
├── docs/                   # Documentation assets
├── packages/               # Shared packages
│   └── types/              # Shared TypeScript types and interfaces
├── scripts/                # Build and maintenance scripts
├── package.json            # Root package.json
└── pnpm-workspace.yaml     # PNPM workspace configuration

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v18 or higher)
• pnpm (v6 or higher)

If you don't have pnpm installed, you can install it globally:

npm install -g pnpm

Getting Started

After checking the prerequisites above, follow these steps to set up the project:

1. Clone the repository

   git clone https://github.com/dulapahv/CodeX.git
   cd CodeX

2. Install dependencies

   This will install all dependencies for the frontend and backend applications:

   pnpm install

   Note: Git hooks will be automatically installed via Husky when running pnpm install

3. Environment setup

   Create apps/client/.env using the template from apps/client/.env.example:

   PISTON_API_KEY=
   BETTERSTACK_API_KEY=
   NEXT_PUBLIC_SENTRY_DSN=
   SENTRY_AUTH_TOKEN=
   GITHUB_CLIENT_SECRET_PROD=
   GITHUB_CLIENT_SECRET_DEV=
   TURBO_TEAM=
   TURBO_TOKEN=

   Note: This is a personal project and the required API keys and secrets are not publicly shared. For local development, you'll need to set up your own credentials for GitHub OAuth, Sentry, etc.

   The backend runs locally with wrangler dev, without a Cloudflare account. Video calls are the exception as they need a Cloudflare Realtime SFU app and TURN key. Create them in the Cloudflare dashboard, preferably separate from production, and put their values in apps/server/.dev.vars:

   SFU_APP_ID=
   SFU_APP_TOKEN=
   TURN_KEY_ID=
   TURN_KEY_API_TOKEN=

   Without them, everything except video calls works.

Development

To start the development server for both the frontend and backend applications:

pnpm dev

You can also start them individually:

# Start only the client
pnpm --filter client dev

# Start only the server
pnpm --filter server dev

The application will be available at:

• Frontend: http://localhost:3000
• Backend: http://localhost:3001

Test

All test commands can be run from both the root directory and their respective workspaces.

Frontend Test

Both the frontend server and the backend server will start automatically. To run the frontend tests:

# In root directory or client workspace
pnpm test:client            # Run all frontend E2E tests
pnpm test:client:ui         # Run frontend tests with UI mode
pnpm test:client:debug      # Debug frontend tests
pnpm test:client:report     # View frontend test report

# Run in client workspace only
pnpm --filter client test:client

The video call tests need the SFU credentials in apps/server/.dev.vars (see Getting Started), so they only run when asked for:

E2E_SFU=1 pnpm test:client

Backend Test

The backend server will start automatically with wrangler dev. Stop pnpm dev first, as both use port 3001. To run the backend tests:

# In root directory or server workspace
pnpm test:server            # Run backend tests against local server
pnpm test:server:remote     # Run backend tests against remote server
pnpm test:server:watch      # Run backend tests in watch mode (local server)

# Run in server workspace only
pnpm --filter server test:server

Build

This project is configured to build both the frontend and backend applications together with caching from Turborepo. To build the entire project:

pnpm build

However, you can also build them individually:

# Build frontend
pnpm build:client

# Build backend
pnpm build:server

The build artifacts of the frontend will be available in the apps/client/.next directory. The backend build is a dry run of wrangler deploy that writes the bundled Worker to apps/server/dist without uploading it.

Deployment

Deployment runs from the GitHub Actions pipeline (.github/workflows/ci.yml) on every push to main, and only after both the server and client test jobs pass:

• Frontend (client): built with the OpenNext adapter and deployed straight to Cloudflare Workers by the workflow
• Backend (server): deployed to Cloudflare Workers with wrangler deploy by the workflow. Each room runs in its own Durable Object, which keeps the room's code, notes and recent terminal output until it has been empty for 5 minutes

The deploy jobs need these repository secrets: CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID (both deploys), and SENTRY_AUTH_TOKEN (source map upload).

The server also needs its video secrets set once on the Worker, where they persist across deploys. wrangler deploy fails until all four are set:

cd apps/server
pnpm exec wrangler secret put SFU_APP_ID
pnpm exec wrangler secret put SFU_APP_TOKEN
pnpm exec wrangler secret put TURN_KEY_ID
pnpm exec wrangler secret put TURN_KEY_API_TOKEN

Scripts

These are the available scripts in the project:

# Development
pnpm dev                    # Start all applications in development mode
pnpm build                  # Build all packages
pnpm build:client           # Build frontend
pnpm build:server           # Build backend
pnpm clean                  # Clean all builds, caches, test results, and node_modules

# Testing
pnpm test:client            # Run frontend E2E tests (Playwright)
pnpm test:client:ui         # Run frontend tests with UI mode
pnpm test:client:debug      # Debug frontend tests
pnpm test:client:report     # View frontend test report
pnpm test:server            # Run backend tests against local server
pnpm test:server:remote     # Run backend tests against remote server
pnpm test:server:watch      # Run backend tests in watch mode (local server)

# Linting and Formatting
pnpm check                  # Check for linting and formatting issues
pnpm fix                    # Fix linting and formatting issues

You can also run scripts in the specific workspaces

Note: This will not use Turborepo caching

# Frontend specific
pnpm --filter client dev
pnpm --filter client build
pnpm --filter client test:e2e

# Backend specific
pnpm --filter server dev
pnpm --filter server build
pnpm --filter server test:socket

Tech Stack

• Frontend:
  • Next.js
  • TypeScript
  • Tailwind CSS
  • shadcn/ui
  • Monaco Editor (code editor)
  • Yjs (CRDT for conflict-free code synchronization)
  • y-partyserver (Yjs provider for the realtime connection)
  • MDXEditor (notepad)
  • PartyTracks (video, voice and screen sharing)
  • Radix Form (form validation)
• Backend:
  • Cloudflare Workers and Durable Objects (one Durable Object per room)
  • TypeScript
  • PartyServer and y-partyserver (WebSocket rooms and Yjs sync)
  • Cloudflare Realtime SFU and TURN (video and voice relay)
  • Yjs (per-room CRDT document that merges, relays and stores edits)
• Testing:
  • Playwright (end-to-end testing for frontend)
  • Jest (backend tests against a local Worker)
  • CodeQL (security analysis)
• Code Quality:
  • Ultracite + Biome (linting and formatting)
  • Husky (git hooks)
  • commitlint (commit message linting)
• Build & DevOps:
  • Turborepo (monorepo build system)
  • GitHub Actions (CI/CD)
  • Cloudflare (frontend and backend deployment)
• Monitoring & Analytics:
  • Sentry (error tracking)
  • Cloudflare Workers Observability (Worker logs, traces and error grouping)
  • Cloudflare Web Analytics (web analytics)
  • Better Stack (uptime monitoring and status page)
• External Services:
  • Piston (code execution)
  • GitHub REST API (repository management)

Coding Style

We use several tools to maintain code quality:

• Ultracite + Biome for linting and formatting
• Husky for Git hooks
• lint-staged for running checks on staged files
• commitlint for commit message linting

Check and fix code style:

pnpm check                  # Check for linting and formatting issues
pnpm fix                    # Fix linting and formatting issues

Contributing

Contributions are welcome! To contribute to this project, follow these steps:

1. Create a new branch for your feature:

   git checkout -b feat/your-feature-name

2. Commit your changes following Conventional Commits:

   git commit -m "<type>(<optional-scope>): <description>"

   • <type>: Must be one of:

     • feat: New features (e.g., "feat: add user authentication")
     • fix: Bug fixes (e.g., "fix: resolve memory leak")
     • docs: Documentation changes (e.g., "docs: update API guide")
     • style: Code style changes (e.g., "style: fix indentation")
     • refactor: Code refactoring (e.g., "refactor: simplify auth logic")
     • perf: Performance improvements (e.g., "perf: optimize database queries")
     • test: Adding/updating tests (e.g., "test: add unit tests for auth")
     • chore: Routine tasks/maintenance (e.g., "chore: update dependencies")
     • ci: CI/CD changes (e.g., "ci: add GitHub Actions workflow")
     • revert: Revert previous changes (e.g., "revert: remove broken feature")
   
   

   For a complete commit message guidelines, see Conventional Commits.

3. Push your changes and submit a Pull Request with a description of your changes:

   git push origin feat/your-feature-name

User Manual

For detailed usage instructions and feature documentation, please refer to the User Manual.

License

Copyright (C) 2024-2026 Dulapah Vibulsanti.

Licensed under the GNU Affero General Public License v3.0 - see LICENSE for the full text.

You are free to use, study, modify and share this project. In return, the AGPL asks two things:

• If you deploy a modified version as a network service, you must offer its complete source to everyone who uses it (AGPL section 13). Running it on a server counts as distribution - this is the difference between the AGPL and the GPL.
• You must preserve attribution. Under an additional term permitted by AGPL section 7(b), the per-file authorship headers must stay intact, and a network-deployed derivative must visibly credit Based on CodeX by Dulapah Vibulsanti in its interface.

The name CodeX, the logo, and the author's name are not covered by the AGPL and may not be used to identify, endorse or promote derived works. See NOTICE for the attribution and trademark terms in full.

Versions released before this change remain available under Apache-2.0; the AGPL applies from this commit onward.