# ozep/cwm architecture

> Architecture diagram of the GitHub repository ozep/cwm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ozep/cwm
- Repository: https://github.com/ozep/cwm

## Overview

##### Project type and purpose
- This is a full-stack, real-time collaborative coding platform (“Code With Me”) built with a React/Vite frontend and a Node.js backend.
- Its purpose is to let two or more users share a live code editor (powered by Yjs and Monaco), execute snippets via the Piston API, and exchange debugging assistance.

##### File structure
Top-level:
- alg/               – Proof-of-concept scripts (Piston API experiments)
- backend/           – Node.js server code
– server.js        – WebSocket & REST endpoints
– question.js      – question/session management
– callback.js      – handles asynchronous Piston callbacks
– utils.js         – axios setup for Piston API
– leetcode-train.jsonl – sample questions data
- public/            – static assets
- index.html         – SPA entrypoint for Vite
- vite.config.js     – Vite build config
- src/               – React application
– main.tsx         – ReactDOM bootstrap
– App.tsx          – root component
– api.js           – HTTP + WebSocket wrapper
– context/         – React Context for WebSocket (SignalWSProvider)
– components/      – UI (CodeEditor, Output, LanguageSelector, etc.)
- package.json       – dependencies (Yjs, monaco-collab, axios, react, etc.)

##### Extract architecture details from README
- Frontend: Vite + React + TypeScript, Real-Time Monaco + Yjs for CRDT syncing
- Backend: Node.js + WebSocket server for low-latency sync
- Code execution: Piston API via axios calls
- No external database: session state is kept in memory or via Yjs documents; questions are served from a JSONL file

A. Client App (browser)
- React UI
- Real-Time Monaco component (Yjs binding)
- SignalWSProvider: maintains WebSocket connection
- Code execution UI → calls api.js to invoke Piston

B. WebSocket Server (backend/server.js)
- Hosts Yjs WebSocket provider for document sync
- Broadcasts CRDT updates between clients
- Emits events for “run code” requests

C. REST / HTTP Endpoints
- POST /execute → callback.js / utils.js → Piston API
- GET /questions → question.js reads JSONL

D. External Service
- Piston API (https://emkc.org/api/v2/piston)

E. Data Storage
- In-memory Yjs documents (CRDT state)
- leetcode-train.jsonl for questions

##### Architectural patterns & design principles
- CRDT-based real-time synchronization (Yjs)
- WebSocket publish/subscribe for low-latency collaboration
- Clear separation of concerns:
- Frontend: UI + state binding
- Backend: sync engine + code execution proxy
- Stateless code-execution proxy (Piston) to maintain sandbox security

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Browsers["Users (Browsers)"]:::external

    %% Frontend Layer
    subgraph "Frontend (Client App)"
        HTML["index.html"]:::frontend
        VITE["vite.config.js"]:::frontend
        Main["src/main.tsx"]:::frontend
        App["src/App.tsx"]:::frontend
        RealTimeMonaco["RealTimeMonaco"]:::realtime
        CodeEditor["CodeEditor"]:::frontend
        Output["Output"]:::frontend
        LangSelector["LanguageSelector"]:::frontend
        QuestionBox["QuestionBox"]:::frontend
        Homepage["Homepage"]:::frontend
        Illustration["Illustration"]:::frontend
        API["api.js"]:::frontend
        WSProvider["SignalWSProvider"]:::realtime
        Toaster["ui/toaster.tsx"]:::frontend
        Tooltip["ui/tooltip.tsx"]:::frontend
        ColorMode["ui/color-mode.tsx"]:::frontend
        ProviderUI["ui/provider.tsx"]:::frontend
        Consts["constants.js"]:::frontend
        Theme["theme.js"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Node.js)"
        Server["server.js"]:::backend
        QuestionJS["question.js"]:::backend
        Callback["callback.js"]:::backend
        Utils["utils.js"]:::backend
        JSONL["leetcode-train.jsonl"]:::backend
    end

    %% External Service
    Piston["Piston API"]:::external

    %% Relationships
    Browsers -->|"loads"| HTML
    HTML -->|"bootstraps"| Main
    Main --> App
    App --> RealTimeMonaco
    App --> CodeEditor
    App --> Output
    App --> LangSelector
    App --> QuestionBox
    App --> Homepage
    App --> Illustration
    App --> API
    App --> WSProvider
    App --> Toaster
    App --> Tooltip
    App --> ColorMode
    App --> ProviderUI
    App --> Consts
    App --> Theme

    RealTimeMonaco -.->|"CRDT sync"| WSProvider
    WSProvider ---|"WebSocket"| Server

    App -->|"execute code"| API
    API -->|"REST POST /execute"| Server
    Server -->|"invoke callback"| Callback
    Callback -->|"uses axios"| Utils
    Callback -->|"executes"| Piston

    App -->|"fetch questions"| API
    API -->|"REST GET /questions"| Server
    Server --> QuestionJS
    QuestionJS --> JSONL
    QuestionJS --> Server
    Server -->|"returns data"| App

    %% Click Events
    click HTML "https://github.com/ozep/cwm/blob/main/index.html"
    click VITE "https://github.com/ozep/cwm/blob/main/vite.config.js"
    click Main "https://github.com/ozep/cwm/blob/main/src/main.tsx"
    click App "https://github.com/ozep/cwm/blob/main/src/App.tsx"
    click RealTimeMonaco "https://github.com/ozep/cwm/blob/main/src/components/RealTimeMonaco.tsx"
    click CodeEditor "https://github.com/ozep/cwm/blob/main/src/components/CodeEditor.tsx"
    click Output "https://github.com/ozep/cwm/blob/main/src/components/Output.tsx"
    click LangSelector "https://github.com/ozep/cwm/blob/main/src/components/LanguageSelector.tsx"
    click QuestionBox "https://github.com/ozep/cwm/blob/main/src/components/QuestionBox.tsx"
    click Homepage "https://github.com/ozep/cwm/blob/main/src/components/Homepage.tsx"
    click Illustration "https://github.com/ozep/cwm/blob/main/src/components/Illustration.tsx"
    click Toaster "https://github.com/ozep/cwm/blob/main/src/components/ui/toaster.tsx"
    click Tooltip "https://github.com/ozep/cwm/blob/main/src/components/ui/tooltip.tsx"
    click ColorMode "https://github.com/ozep/cwm/blob/main/src/components/ui/color-mode.tsx"
    click ProviderUI "https://github.com/ozep/cwm/blob/main/src/components/ui/provider.tsx"
    click API "https://github.com/ozep/cwm/blob/main/src/api.js"
    click WSProvider "https://github.com/ozep/cwm/blob/main/src/context/SignalWSProvider.tsx"
    click Consts "https://github.com/ozep/cwm/blob/main/src/constants.js"
    click Theme "https://github.com/ozep/cwm/blob/main/src/theme.js"
    click Server "https://github.com/ozep/cwm/blob/main/backend/server.js"
    click QuestionJS "https://github.com/ozep/cwm/blob/main/backend/question.js"
    click Callback "https://github.com/ozep/cwm/blob/main/backend/callback.js"
    click Utils "https://github.com/ozep/cwm/blob/main/backend/utils.js"
    click JSONL "https://github.com/ozep/cwm/blob/main/backend/leetcode-train.jsonl"

    %% Styles
    classDef frontend fill:#DCEEFB,stroke:#0366D6,stroke-width:1px;
    classDef realtime fill:#D1FADF,stroke:#15803D,stroke-width:1px;
    classDef backend fill:#FEF3C7,stroke:#B45309,stroke-width:1px;
    classDef external fill:#E5E7EB,stroke:#6B7280,stroke-width:1px;
```
