Documentation
Sonar now spans two closely connected products: the Sonar Code Editor desktop app for actual coding and monitored collaboration, and the Sonar web app for public pages, downloads, host authentication, hackathon management, and monitoring review.
Platform Overview
Sonar Code Editor App
The Electron desktop client used by participants and teams for coding, collaboration, previewing, logging activity, and consuming invite links.
Sonar Web App
The SvelteKit website and host portal used for downloads, public pages, host auth, hackathon management, monitoring, and settings.
Code Editor App: Installation & Packaging
The desktop client lives in Sonar-Code-Editor and ships as an Electron application with native packaging targets.
Prerequisites
- Node.js 18 or newer
- npm
- Git
- Appwrite configuration for authentication and telemetry-backed flows
Local Development
cd Sonar-Code-Editor
npm install
npm run start
Build & Packaging
npm run build
npm run package
npm run package:mac
npm run package:win
npm run package:win:all
npm run package:win:store
npm run package:linux
Code Editor App: Editor Experience
The desktop app is built around the Monaco Editor, Jack-File-Tree, and Jack-Editor-Tab libraries, providing a VS Code-style editing surface adapted for collaborative and supervised workflows.
Core capabilities
- Monaco Editor with syntax highlighting and language-aware editing (powered by VS Code engine)
- Jack-File-Tree: Custom high-performance tree navigation with inline operations
- Jack-Editor-Tab: Sophisticated multi-tab management and state recovery
- Isolated Preview Panel (restricted webview) with localhost-only access for secure local development
- Multi-tab editing with preview/image tabs alongside source files
- Auto-save and word-wrap controls, plus configurable collaboration name overlays
- Dependency-file change prompts that remind collaborators to run the correct install command locally
- Version gating before login so outdated desktop builds can be blocked when required
- Offline-first design: all core assets (including Monaco workers) are bundled locally
Common language support
Code Editor App: Workspace & File Tree
Capabilities
- Custom file tree with create, rename, delete, nested folders, and inline operations
- Image and binary file handling so unsupported content does not break the text editor
- Cross-platform relative path normalization for collaboration sync across Windows and macOS/Linux paths
- Key-shielded file tree input handling to reduce focus conflicts in the desktop shell
- Workspace-root aware behavior so file operations stay scoped to the active project
Custom Libraries
Code Editor App: Collaboration & Invites
Collaboration in the desktop client is optimized for real-time team work and controlled event participation rather than generic cloud document sharing.
- Jack-File-Tree and Jack-Editor-Tab integration for high-performance state synchronization across peers
- Conflict-free Replicated Data Types (CRDTs) powered by Yjs for seamless real-time sync
- Real-time synchronization of code, cursor positions, and selections via y-monaco and y-websocket
- CollaborationManager: initiates and hosts peer-to-peer style sessions on a local network
- Custom sonar-editor:// URI protocol handler for seamless deep-link session joining
- Awareness scaling: multi-user tracking with distinct colors and names
- Host Session and Join Session flows with integrated firewall/network check prompts
- Full workspace sync (folder structure, files, edits) on connection via Jack-File-Tree, not just text buffers
- Shareable hackathon/team invite links that route through the website download flow
- Explicit reminder that node_modules is not shared and must be installed locally
Code Editor App: Search & Productivity
- Workspace search through Electron IPC
- Debounced search input for large projects
- Case-sensitive and whole-word matching options
- Results grouped by file with expand/collapse behavior
- Search skips `node_modules` and opens files directly at the matched line
Code Editor App: Monitoring Capture
Code Editor App: Local Preview
- Integrated Preview Panel: Flexible sidebar view for real-time web previews alongside the editor
- Preview Tabs: Standard workspace tabs that render HTML content as fully functional browser-based views
- Sticky Preview: Lock the preview to a specific file or port while continuing to navigate other project files
- Follow-file mode: The preview surface can be toggled to automatically track and reload when changing active editors
- Embedded local preview backed by a desktop static server that finds an open port automatically
- Reload-on-save support for immediate iteration directly inside the IDE
- Strict localhost-only navigation: any local port can be accessed but only via a localhost URL, completely blocking external browsing
- Back, forward, refresh, and console message interception for debugging preview-originated signals
Code Editor App: Settings & Team Tools
Text Editor
Auto-save, hot reload, word wrap, and other coding experience preferences.
Appearance
Theme and accent behavior that persists locally for the desktop UI.
Collaboration
Display collaborator usernames and adjust label opacity for shared editing.
Account
View the current team, manage invite generation, and add team members from the settings modal.
Activity Log
Generate and export comprehensive PDF session reports through the desktop client.
Security
Change the team password and use password-backed team invites when enabled.
Code Editor App: Security Model
Team login model
The desktop app signs teams in with hackathon ID, student ID, and password, then applies effective restriction settings from the platform.
Workspace containment
Path handling, workspace-root scoping, and preview URL validation keep operations inside the intended project boundary.
Network restriction awareness
Hackathon and global internet restrictions can block normal usage patterns when the event requires a more controlled environment.
Operational telemetry
Session-close sync, local security logs, and monitoring hooks help maintain a traceable record of IDE behavior.
Code Editor App: Release Hardening
Build pipeline
build renderer + main + preload
compile bytecode
generate build attestation
package with Electron Builder
Runtime protections
- Builds compile JavaScript to bytecode during the packaging pipeline.
- A build attestation file is generated so packaged releases can expose signed build metadata.
- Packaged apps verify an ASAR integrity seal and signature before continuing.
- A renderer heartbeat watchdog detects prolonged unresponsiveness or tampering-like pauses.
- Security log entries are chained with HMACs for stronger local auditability.
- The desktop app registers the `sonar-editor://` protocol to accept invite handoff from the website.
- Electron Builder packaging targets include macOS, Windows, and Microsoft Store AppX flows.
Web App: Route Map
Public Routes
/
Marketing landing page with adaptive download CTAs and host entry points.
/docs
Combined documentation for both the desktop editor and the web platform.
/download
Installer page plus deep-link landing route for desktop invites.
/windows/download
Windows-specific redirect page that fetches the latest GitHub release installer.
/about
Project story plus live GitHub contributor list.
/contact
Progressively enhanced contact form with acknowledgement email.
/privacy and /terms
Public legal pages linked from the site and host flows.
Host & Dashboard Routes
/admin
Session gate that refreshes auth and redirects into the proper host route.
/admin/signin and /admin/signup
Email and OAuth entry points for hosts.
/admin/complete-registration
OAuth completion step that captures account structure details.
/admin/verify-email, /admin/forgot-password, /admin/reset-password
Verification and recovery routes for host accounts.
/admin/dashboard
Overview metrics, charts, refresh controls, and live summaries.
/admin/dashboard/hackathons
Hackathon listing, filtering, and event creation drawer.
/admin/dashboard/monitoring
Cross-hackathon telemetry, risk summaries, and saved report access.
/admin/dashboard/settings
Host defaults, account security, and appearance controls.
/admin/dashboard/hackathons/[hackathonId]
Per-event overview, analytics, and settings workspaces.
Web App: Public Site
Shared site chrome
The public layout carries docs, about, contact, download, theme switching, and a dynamic sign-in/dashboard CTA based on auth state.
Adaptive download entry
The landing page changes the primary call to action by user agent, favoring Homebrew on macOS and the Microsoft Store on Windows.
Public/admin separation
Admin routes live under `/admin` and most are marked `noindex`, while public content stays crawlable.
Web App: Download & Handoff
Installer flows
- macOS surfaces copyable Homebrew install and upgrade commands.
- Windows users can be routed toward the Microsoft Store or a release download flow.
- The Windows-only download route can resolve the latest GitHub release asset automatically.
Native app handoff
/download?invite=...maps into the desktop protocol handler.- Hackathon and student ID parameters can prefill the desktop login experience.
- The page probes the custom protocol and falls back gracefully to install guidance.
This route is the bridge between host-generated web invites and the desktop code editor experience.
Web App: Contact & Legal
Contact form
The contact route uses a SvelteKit form action with validation, immediate UI feedback, background email sending, and acknowledgement mail to the sender.
Legal pages
Privacy and terms are published as first-class public routes so the website and host flows can reference a stable policy surface.
Web App: Host Authentication
Email sign up
Creates an Appwrite account, starts a session immediately, stores host profile details in account prefs, and attempts email verification.
OAuth sign in/up
Google and GitHub redirect through `/admin/auth/callback`, then continue to completion or dashboard routes depending on state.
Registration completion
OAuth users finish onboarding on `/admin/complete-registration`, selecting `individual` or `organization` and filling organization details when needed.
Route resolution
Authenticated hosts are routed by `resolveAuthenticatedRoute` into completion, verification, or dashboard experiences.
Normalized host profile
The web auth layer maps roles, registration state, account type, organization metadata, password state, and linked auth providers from Appwrite prefs.
Web App: Dashboard Overview
- The admin layout starts polling, manages mobile/collapsed navigation, and resets content scroll on navigation.
- The overview page shows live teams, total teams, saved report count, risk distribution, and top application usage charts.
- The shared admin store keeps a 30 second freshness window and polls for updates every 20 seconds.
- Manual refresh is available across dashboard pages without forcing a full route reload.
Web App: Hackathons
- Hackathons are created with name, description, status, dates, and restriction defaults inherited from global host settings.
- Public hackathon IDs are normalized to 12 digits and generated with a Luhn-style check digit.
- Listing supports text, date, and status filters for larger host workspaces.
- Each hackathon gets overview, analytics, and settings pages under its own route branch.
- Hosts can copy a hackathon ID or a website invite URL that opens the desktop app handoff flow.
- Hackathon settings support per-event override edits and destructive deletion.
Web App: Monitoring & Analytics
Web App: Host Settings
Global host defaults
Hosts can set default hackathon restrictions such as `blockInternetAccess` and `blockNonEmptyWorkspace`.
Account security
The dashboard settings page includes in-session password changes through the Appwrite account API.
Appearance
Theme mode and accent color are stored locally and applied as runtime dashboard CSS overrides.
Hackathon-level overrides
Each event can override restrictions and metadata in its own settings page.
Data Layer
Code Editor App
Electron 35, React 18, Monaco Editor, Jack-File-Tree, Jack-Editor-Tab, Yjs/y-websocket, Appwrite, electron-store, jsPDF, and Electron Builder.
Web App
SvelteKit 2, Svelte 5 runes, Tailwind CSS 4, Appwrite Account/Database/Functions, Chart.js, and Nodemailer.
Shared platform services
Appwrite collections, function-based fallbacks, invite handoff through the website, and telemetry flowing from desktop into host-facing analytics.
- The desktop app emits telemetry and session updates while the web app aggregates and presents them.
- Direct Appwrite reads are attempted first in the web portal, with function-based fallback when permissions are still migrating.
- Hackathon writes in the web portal can degrade to local browser storage when Appwrite writes fail, with warnings shown to the host.
- Desktop collaboration is LAN-oriented, while web invite links bridge users into the native client through `/download`.
Environment Reference
Code Editor
VITE_APPWRITE_ENDPOINT The Appwrite server endpoint URL.VITE_APPWRITE_PROJECT_ID Your Appwrite project identifier.VITE_APPWRITE_DB_NAME The database name for operations.VITE_APPWRITE_COLLECTION_* Collection IDs for teams, sessions, activityLogs, reports, settings, hackathons, and hackathonParticipants.VITE_SONAR_WEBSITE_URL Base URL used to generate shareable invite links back to the web platform.VITE_SONAR_INVITE_SECRET Optional secret to enable encrypted team invite links with password-based auto-login.COL_HACKATHONS Function/runtime collection ID for hackathons.COL_HACKATHON_PARTICIPANTS Function/runtime collection ID for hackathon participants.Web App
VITE_APPWRITE_ENDPOINT The Appwrite server endpoint for the host portal.VITE_APPWRITE_PROJECT_ID Your Appwrite project identifier.VITE_APPWRITE_DB_NAME Database name for admin data reads.VITE_APPWRITE_COLLECTION_* Collection IDs for sessions, activityLogs, reports, settings, and hackathons.VITE_APPWRITE_FUNCTION_SETTINGS Function ID for resolving function-based settings and fallbacks.VITE_SONAR_WEBSITE_URL Base URL to build absolute invite URLs from host hackathon pages.VITE_DEV_KEY API key required to access our cloud server and database during development.Server & Build
SMTP_* SMTP configuration vars (HOST, PORT, SECURE, USER, PASS, FROM) and optional CONTACT_INBOX_EMAIL for the website contact form.BUILD_SIGNING_KEY Produces signed build attestation payloads for official desktop releases.SEAL_PRIVATE_KEY PEM string used strictly during packaging to cryptographically seal the ASAR archive.SEAL_PUBLIC_KEY Embedded inside packaged desktop builds to verify integrity seals at runtime and in release verification scripts.Architecture & Infrastructure
Sonar Ecosystem
A dual-app architecture: The Electron-based Sonar Code Editor acts as the frontend work environment while the Sonar Web App (SvelteKit) serves as the host portal and web invite bridge.
Database & Backend (Appwrite)
Appwrite provides a centralized backend. Collections separate Hackathons, Participants, Sessions, Logs, and Settings. Everything runs through Appwrite permissions to map roles between hosts and developers.
Real-time Collaboration & Synchronization
Peer-to-peer real-time editing relies on Yjs (CRDTs) over y-websocket in the Code Editor, while workspace state (like file trees and active tabs) is synced seamlessly across peers using our custom Jack-File-Tree and Jack-Editor-Tab libraries. Broad telemetry and global events broadcast via Appwrite Realtime.
Serverless Functions
Appwrite Functions act as the secure intermediary for operations that shouldn't grant full client-side trust (e.g., host settings fallback, participant enrollment gating, complex database updates).
Offline-First Editor
The IDE ensures developers can write code, commit actions, and stash monitoring payloads locally (Offline Resilience) using electron-store and IndexedDB, flushing the data once the connection restores.