Documentation

Sonar IDE is a real-time collaborative code editor built with Electron + React + Vite, designed for supervised coding environments, pair programming, and monitored exams. It combines the power of the Monaco Editor (the engine behind VS Code) with comprehensive activity monitoring and administrative controls.

Whether you're an administrator setting up exam sessions or a student writing code, this documentation covers everything from installation to advanced features.

Installation

Prerequisites

Node.js v18.x or higher
NPM v9.x or higher
Git

Local Development

# Clone and install

git clone https://github.com/your-username/Sonar-Code-Editor.git

cd Sonar-Code-Editor

npm install

# Start all processes (Vite + TypeScript + Electron)

npm run start

Production Build

npm run build

npm run package:win # Windows NSIS installer

npm run package:mac # macOS DMG

npm run package:linux # Linux AppImage

Code Editor

Powered by the exact Monaco Editor engine from VS Code, Sonar supports 100+ programming languages with full syntax highlighting, IntelliSense, auto-closing brackets, and code formatting.

Editor Features

Multi-tab file editing with visual tab bar
Auto-save with configurable 500ms debounce
Toggleable word wrap and minimap
JetBrains Mono font with ligatures
Smooth scrolling and cursor blinking
Auto-closing brackets, quotes, and HTML tags

Supported Languages

TypeScriptJavaScriptHTMLCSSJSONPythonRustGoJavaCC++PHPSQLMarkdownYAMLBash

Admin-Controlled Editor Policies

To maintain strict exam environments, advanced editor behaviors such as quick suggestions (autocomplete), snippet completions, and auto-closing brackets/quotes can be dynamically enabled or disabled globally by an administrator in the admin dashboard settings. This prevents over-reliance on IntelliSense and enforces academic integrity when needed.

File Tree & Workspace

The File Tree provides full workspace management with right-click context menus and inline rename for effortless navigation.

Recursive folder expansion with type-specific file icons
Right-click context menu for create, delete, and rename operations
Inline rename with double-click (Enter to commit, Esc to cancel)
Binary file detection — images displayed in a preview tab
Platform-aware indentation (Windows: 16px, macOS: 28px)
Global undo restores the last deleted file from an internal trash buffer
KeyShield captures input at the window level to prevent React focus conflicts

Live Collaboration

Google Docs-style real-time code collaboration powered by Yjs (CRDT) and y-monaco bindings. All changes are synchronized automatically with conflict-free resolution — no manual merging required.

How It Works

1. Host starts session — A user initiates a collaboration session and shares their session details.

2. Client joins — Other team members enter the shared address to connect securely.

3. Team validation — The system verifies the joining client's team ID to ensure authorized access only.

4. Workspace sync — Full workspace structure and file contents are automatically synchronized.

5. Live editing — Every change is synced in real-time. Shared cursors show each user's position with a unique color and name label.

Cursor Colors

Blue

Green

Amber

Red

Violet

Pink

Cyan

Lime

Activity Monitoring

The monitoring system operates through a dual-layer architecture: the Main Process sends heartbeats every 15 seconds, while the Renderer tracks local activity events and attaches them to each heartbeat before syncing to Appwrite.

Tracked Events

Online/Offline Status Monitors network connectivity and records disconnected states

Window Focus Detects when a user leaves the IDE or switches focus away

Internal Copy/Paste Tracks copy and paste operations within the editor

External Paste Detection Alerts when content is pasted from an external source

Active Applications Records which applications the user is actively viewing

Current File Logs which file the user is currently editing

Offline Resilience

If the network is unavailable, activities are queued safely in local storage. Once the connection is restored, all queued events are transparently synced to provide gapless monitoring without disrupting the user.

Admin Dashboard

Users with role: 'admin' are routed to a dedicated monitoring dashboard with real-time visibility into all active teams and their activity.

Real-time Monitoring

Live team list with online/offline status
Tracking of last seen timestamp
Visibility into current active windows and files
Reliable status updates with robust fallbacks

Activity Metrics

Total heartbeats, unique apps, files, and windows
Online/offline duration tracking
Clipboard copy count and external paste detection
App blur events (suspected app switches)

Dashboard Views

Table mode (compact, columnar) and Grid mode (card-based)
Sort by: Team Name, Status, or Last Seen
Filter by: All, Online Only, or Offline Only
Case-insensitive search by team name

PDF Report Generation

Per-team detailed reports via jsPDF
Summary: total time, online %, disconnections, app switches
Online/offline timeline with durations
Suspicious app detection (browsers, chat, AI tools)

Global Dashboard Insights

Online/offline user count with percentage breakdown
Top 5 most-accessed external applications
Recently active teams (within last 5 minutes)
Estimated average session duration

Local Preview

The integrated preview panel embeds a <webview> restricted to localhost-only URLs. All non-localhost navigation is silently blocked, preventing exam candidates from accessing external websites.

Navigation Controls

Back

Forward

Refresh

Home

Embedded Express server starts from port 3500 (auto-finds free port)
Serves static files from workspace with no-cache headers
Follow File mode: auto-navigates to the active .html file
Hot reload: refreshes preview on every file save (toggleable)
Console capture: intercepts log, warn, error from the loaded page (last 500 entries)
Inspector button opens DevTools for the webview
Supports: HTML, CSS, JS, images, fonts, media, PDFs

Settings

The settings modal provides tabs for customizing the IDE experience. User settings persist to localStorage. Administrator actions sync globally in real-time.

Student & General Settings

Text Editor

Auto-Save (500ms debounce), Hot Reload (refresh preview on save), Word Wrap toggle

Appearance

Theme: Light, Dark, or System (respects OS preference on load)

Collaboration

Show collaborator usernames toggle, username opacity slider (0-100%)

Account

View team name, list team members (student IDs), add members (max 5)

Activity Log

View event timeline, export as color-coded PDF with suspicious activity flags

Security

Change team password (requires current password verification)

Admin Settings & Overrides

Administrators have access to global management settings that bypass local student choices.

Editor Restrictions

Locally disable Monaco's built-in Quick Suggestions (Autocomplete), Snippet Completions, and auto-closing brackets.

Network Constraints

Toggle and enforce Global Internet Restrictions to completely sandbox the team.

Log Management

Safely clear flagged activity logs globally or manage team connection states.

Activity Policies

Define strict conditions for what constitutes an external paste or blur event.

Security Model

Sonar enforces multiple layers of security to maintain academic integrity during exams.

Team-Based Authentication

Users authenticate with Team Name + Password via Appwrite. Offline fallback uses locally cached credentials with a simple hash. Role-based routing sends admin users to the dashboard and team users to the IDE.

Input Sanitization

System operations are carefully guarded to ensure all generated files remain within their isolated workspace root. Restricted characters are rejected completely to prevent traversal attacks.

Preview Lockdown

The <webview> element intercepts all navigation requests and validates them against a strict localhost-only policy:

Only localhost:* and 127.0.0.1:* URLs are permitted
Non-localhost URLs are silently ignored (redirected to server root)
URL bar input auto-prepends http:// for bare localhost entries
All responses include Cache-Control: no-cache headers

This ensures exam candidates cannot browse the web, access external APIs, or open any online resources from within the IDE.

File System Sandbox

The application guarantees an isolated environment by ensuring editors have zero direct access to the computer's underlying file system.

Binary files gracefully exclude disruptive contents from the editor pane
Missing directory structures are securely generated during sync operations
System configurations (e.g. environment files) remain securely hidden off-screen

Tech Stack

Frontend

React
Monaco Editor
Yjs (CRDT)
Lucide Icons
Tailwind CSS
Appwrite Service

Desktop & Build

Electron
Electron Builder
TypeScript
Vite

Changelog

v1.0.0-beta Initial Beta Release

Real-time collaborative code editing powered by Monaco Editor and Yjs
Secure Admin dashboard for user monitoring and activity tracking
Custom File Tree navigation and multi-document tabs handling
Integrated Preview Panel restricted to localhost domains only
Context Bridge secure IPC between Main and Renderer processes
Appwrite authentication and cloud synchronization integration
Offline behavior logging with PDF generation via jsPDF
WebSocket-based P2P file sharing and workspace synchronization
Activity event tracking: online/offline, app focus/blur, clipboard operations
Support for 100+ programming languages via Monaco Editor
Cross-platform compatibility: Windows, macOS, Linux with native installers

Reporting Security Vulnerabilities

Security issues should not be reported as public GitHub issues. Please email security@knurdz.org with a detailed disclosure. See SECURITY.md for the full policy.