🪐 Helio Codebase Documentation
What is Helio?
In Simple Terms: Helio is a real-time collaborative code editor - think Google Docs, but for coding. Multiple developers
can write code together simultaneously, see each other's cursors, chat, use a shared whiteboard, and execute code
directly in the browser.
Technically: It's a full-stack MERN (MongoDB, Express, React, [Link]) application using WebSockets ([Link]) for real-
time communication and CRDTs (Conflict-free Replicated Data Types) via Yjs to handle concurrent edits without conflicts.
Root Level Structure
File/Folder Purpose
client/ React frontend application
server/ [Link]/Express backend + [Link] server
[Link] Root package with scripts to run both client & server concurrently
scripts/ Utility scripts for debugging/testing
*.sh files Shell scripts for testing and verification
CLIENT (Frontend) - /client/src/
Core Files
File Simple Explanation Technical Details
The main app - defines all React Router setup with AuthProvider and ThemeProvider context
[Link]
pages/routes wrappers
[Link] Entry point that renders App Mounts React to DOM
[Link] Global state container Redux Toolkit store for whiteboard state
[Link] Global styling CSS variables, glassmorphism design system
[Link] Base/reset styles Font imports, CSS resets
/pages/ - Application Pages
File Simple Explanation Technical Details
Landing page - enter/generate room UUID generation for room IDs, hero section with
[Link]
codes animations
User dashboard - view room history, Fetches user's recent rooms and friend list from
[Link]
friends API
[Link] Login form JWT-based auth, Google OAuth support
[Link] Multi-step registration Email verification with OTP via Brevo
[Link] Password recovery OTP-based password reset flow
[Link] User profiles Avatar customization, bio, social handles
[Link] Direct messaging 1-on-1 chat with friends
[Link] OAuth redirect handler Stores JWT token after Google login
[Link] Error page Generic server error display
/components/ - Reusable Components
Core Editor Components
File Simple Explanation Technical Details
THE MAIN EDITOR (~1300 Monaco Editor + Yjs for CRDT sync, file tabs, code execution, chat
[Link]
lines) panel, WebRTC video
[Link] Monaco Editor wrapper Configures syntax highlighting, themes, keybindings
[Link] User avatar in sidebar Shows connected collaborators with colored indicators
[Link] In-room chat component [Link] message broadcasting
[Link] Video call UI WebRTC peer connections display
UI Components
File Purpose
[Link] Top navigation bar
[Link] User/room search
[Link] Page layout wrapper
[Link] Auth guard for protected pages
[Link] Room creation dialog
[Link] Avatar picker
/Whiteboard/ - Collaborative Canvas
File Purpose
[Link] Main infinite canvas (~22KB) - drawing, shapes, text
[Link] Tool palette - shapes, colors, stroke settings
[Link] Redux state for whiteboard
utils/ Element creation, intersection, roughjs rendering
constants/ Tool types, element types, colors
/context/ - React Context Providers
File Purpose
[Link] Global auth state - current user, JWT token, login/logout
[Link] Light/Dark mode toggle for the editor
/services/ - API Communication
File Purpose
[Link] [Link] client initialization
[Link] CRDT synchronization - binds Yjs documents to [Link]
/hooks/ , /utils/ , /config/
Folder Purpose
hooks/ Custom React hooks
utils/ Helper functions
config/ Action constants, API URLs
SERVER (Backend) - /server/
Entry Point
File Simple Technical Details
Explanation
Server startup Express + [Link] setup, MongoDB connection, route mounting, CORS config,
[Link]
rate limiting
/src/models/ - Database Schemas (MongoDB)
Model Simple Explanation Key Fields
[Link] User accounts username, email, password (hashed), friends, recentRooms, avatar
[Link] Coding rooms roomId, name, owner, files[], whiteboardElements[]
[Link] Room chat history roomId, message, sender, timestamp
[Link] Direct messages For 1-on-1 friend chats
[Link] Friend system sender, receiver, status (PENDING/ACCEPTED)
[Link] Code execution logs roomId, codeSnapshot, action, timestamp
/src/routes/ - API Endpoints
Route File Endpoints Purpose
[Link] /api/auth/* Login, register, OTP verify, password reset
[Link] /api/users/* Profile CRUD, friend requests, search
[Link] /api/rooms/* Room history, save room data
[Link] /api/chat/* Get/save direct messages
[Link] /api/run/* Execute code via Piston API
[Link] /api/logs/* Fetch audit logs
[Link] /metrics Health checks
/src/controllers/ - Business Logic
Controller What It Does
[Link] Password hashing (bcrypt), JWT signing, OTP generation/verification
[Link] Profile updates, friend management, user search
[Link] Room CRUD, member management
[Link] Message persistence
[Link] Piston API integration for code execution
[Link] Audit log queries
/src/services/ - Core Services
Service Simple Explanation Technical Details
Heart of real-time Handles all [Link] events: JOIN, CODE_CHANGE, SYNC, FILE
[Link]
operations, WebRTC signaling, cursor positions
[Link] Room operations Create/find rooms, add members, persist files
Yjs document Stores in-memory Yjs docs per room for CRDT sync
[Link]
management
/src/middleware/ , /src/utils/ , /src/config/
Folder Purpose
middleware/ JWT verification, auth guards
utils/ Logger (Winston), helper functions
config/ [Link] (Google OAuth), environment setup
constants/ [Link] - Socket event names (JOIN, LEAVE, CODE_CHANGE, etc.)
How Real-Time Collaboration Works
User A types 'hello' → Yjs creates binary update → [Link]('SYNC_UPDATE')
↓
[Link] Server
↓
[Link]('SYNC_UPDATE') to room
↓
User B receives update → Yjs merges with CRDT algo → Monaco updates
Key Insight: CRDTs ensure that even if User A and B type simultaneously at the same position, their changes are merged
deterministically without conflicts.
Security Features
Bcrypt - Password hashing
JWT - Stateless authentication
Helmet - Secure HTTP headers
Rate Limiting - Prevents brute force attacks
CORS - Controlled origin access
External Integrations
Service Purpose
Piston API Sandbox code execution (Python, C++, Java, etc.)
Brevo (Sendinblue) Email OTP for verification
Google OAuth Social login
MongoDB Atlas Cloud database
Tech Stack Summary
Layer Technology Purpose
Frontend React 18 Declarative UI Library
Monaco Editor Text Editor Component
[Link]-Client Real-time WebSocket Communication
Yjs CRDT for conflict-free editing
Redux Toolkit State management (whiteboard)
Framer Motion Animations
Backend [Link] & Express Server Runtime & API Framework
[Link] Event-based Bidirectional Communication
Mongoose MongoDB Object Modeling
Security JSON Web Token (JWT) Stateless Authentication
[Link] Password Hashing
Helmet & Rate-Limit API Security Hardening
External Piston API Remote Code Execution Sandbox
Brevo Transactional Email Service (OTP)
Generated on December 24, 2025