Documentation // Cloud Code Compiler

01. Architecture

The platform operates as a distributed system designed for low-latency feedback. It replaces traditional HTTP polling with persistent WebSocket connections, enabling interactive coding (REPL-like behavior) over the web.

Frontend (Client)

• Editor: CodeMirror 5 (Dracula Theme)
• Terminal: Xterm.js with FitAddon
• State: Browser LocalStorage
• Intelligence: Client-side Error Parsing

Backend (Server)

• Server: Python aiohttp (AsyncIO)
• Runtime: subprocess pipelines
• AI Engine: Google Gemini 2.5 Flash
• Database: Firebase Firestore (NoSQL)

02. Professional Editor Experience

Replaced the standard textarea with CodeMirror to provide an IDE-grade environment directly in the browser.

Visual & Editing

• Syntax Highlighting: Dracula theme for easy reading.
• Line Numbers: Essential for debugging.
• Bracket Matching: Visual cues for matching parentheses.
• Auto-Indent: Smart indentation for Python and C++.

Developer Tools

• Undo/Redo: Ctrl+Z / Ctrl+Y support with history stack.
• Mobile Helper Bar: Sticky keys for { } [ ] ; on touch devices.
• Export: Download code as .py, .c, or .cpp files.
• Clear Code: Quick reset with confirmation modal.

03. WebSocket I/O Protocol

Real-time interaction handles input/output streams efficiently. The server streams stdout characters immediately, preventing "hanging" on long-running processes.

// 1. Run Command (Client -> Server)
{ "type": "run", "language": "python", "code": "print('Hello')" }

// 2. Output Stream (Server -> Client)
// Streamed character-by-character or line-by-line
{ "type": "stdout", "data": "H" }
{ "type": "stdout", "data": "e" } ...

// 3. User Input (Client -> Server)
// Sent when user types in terminal
{ "type": "input", "data": "user_input\n" }

04. Execution Engines

Each language runs in a specialized, isolated subprocess on the backend.

Python 3 Engine

The Python environment runs on the latest stable Python 3 release.

Execution: Code is written to a temporary file and executed via `python3 -u` (unbuffered) to ensure real-time output.
Pip Packages: The environment comes pre-configured with standard libraries. pip is available in the backend environment, allowing for pre-installed packages to be imported (e.g., math, time, random).
Indentation: The editor converts Tabs to 4 Spaces automatically to prevent IndentationError.

C / C++ Compiler

Powered by the GNU Compiler Collection (GCC).

C Language: Compiles via `gcc source.c -o app -lm -pthread`. Uses standard C11/C17 standards.
C++ Language: Compiles via `g++ source.cpp -o app -lm -pthread`. Supports modern C++ standards.
Extended Support: Explicitly links against the Math library (-lm) and Threads library (-pthread), enabling advanced mathematical operations and multi-threaded applications.
Binary Execution: After compilation, the binary is immediately executed (`./app`), and output is piped to the WebSocket.
Error Handling: Compilation errors (stderr) are captured and displayed in red in the terminal.

Performance Notes

This project is currently hosted on Render’s free tier, which utilizes automatic sleep cycles to conserve resources. This introduces specific behavior patterns:

Cold Starts: The first execution after a period of inactivity may take several seconds due to the container waking up.
Warm Execution: Subsequent runs happen in real-time and are significantly faster.
CPU Limits: CPU-intensive Python benchmarks are not representative of real-world interactive usage on this deployment.

05. AI Auto-Debug System

The compiler monitors the output stream for common error patterns (e.g., Traceback, Segmentation fault, error:).

How it works:

Capture: The client buffers the last 4KB of terminal output.
Trigger: If an error keyword is found, the "Ask AI" button appears.
Processing: Code + Error Log is sent to Gemini 2.5 Flash.
Response: The AI generates a JSON object containing a plain-English explanation and the corrected code block.
Patch: The user can review the fix in a modal and apply it to the editor instantly.

06. Sharing & Persistence

Data storage is handled in two distinct layers to balance privacy and collaboration.

Local Persistence

Every keystroke is saved to the browser's localStorage. This data never leaves your device until you execute or share it.

Cloud Sharing

Uploads a snapshot to Firebase generating a short 7-char ID (e.g., ?share=AbC123X).

Base64 / LZ Fallback

Code can be encoded directly into the URL (e.g., ?code=...).
Pro Tip: Use LZ-String compression to reduce URL length by ~60% vs standard Base64.

07. Data Lifecycle

Stage	Storage Location	Duration	Accessibility
Drafting	Browser LocalStorage	Persistent (User Control)	Private (Device Only)
Execution	Server RAM / Temp File	Ephemeral (Seconds)	System (Deleted after run)
Sharing	Firebase Firestore	Permanent	Public (Link Holders)

08. Security Implementation

Security is enforced at the environment level to prevent abuse.

Sanitized Environment

Subprocesses run with a stripped environment (`safe_env`). API keys, system paths, and sensitive variables are removed from the execution context.

Session Isolation

Each client connection generates a unique UUID-based session directory (e.g., `temp_sessions/abc-123`). All temporary files are created within this isolated sandbox and are automatically wiped upon disconnection, preventing data leakage between concurrent users.

09. Developers & Contribution

We welcome contributions from the community. Whether you've found a bug, want to suggest a feature, or add support for a new language, here is how you can get involved.

Open Source

The core infrastructure is open-source. Clone the repo, create a branch, and submit a Pull Request.

Report Bug Fork Repo

Direct Contact

For security vulnerabilities, private feedback, or collaboration inquiries, please email directly.

amitdutta4255@gmail.com

10. Legal & Disclaimer

This compiler infrastructure utilizes Google's Generative AI services and Firebase for data storage.

Disclaimer of Liability: This tool is provided "as is". Amit Dutta assumes no responsibility or liability for any consequences, errors, or data loss arising from the use of this compiler. This project is provided for demonstration purposes only.

"I explicitly disclaim any affiliation with or responsibility for the ongoing operation of this project. I reserve the absolute right to modify, suspend, or permanently delete this compiler and its associated services at any time, for any reason, without prior notice."

System Documentation