A modern, cross-platform desktop application for real-time team collaboration.
Features β’ Installation β’ Development β’ Building β’ Architecture β’ Contributing β’ License
- Overview
- Features
- System Requirements
- Installation
- Development
- Building
- Architecture
- Configuration
- Testing
- Deployment
- Troubleshooting
- Contributing
- License
- Acknowledgments
ZYNC is a real-time collaboration platform built for development teams who need seamless communication, project management, and code collaboration tools in one unified interface. The desktop application extends the web platform with native operating system integrations that enhance productivity and user experience.
While the ZYNC web application provides full functionality through any modern browser, the desktop application offers several advantages that justify its existence as a standalone native application:
-
System Tray Integration: ZYNC runs in the background and provides instant access through the system tray icon, allowing users to stay connected without keeping a browser tab open.
-
Native Notifications: Desktop notifications are delivered through the operating system's native notification system, ensuring they are visible even when the application is minimized or in the background.
-
Keyboard Shortcuts: Global keyboard shortcuts allow users to quickly access ZYNC features from anywhere on their desktop, regardless of which application is currently in focus.
-
Auto-Updates: The application automatically checks for and installs updates, ensuring users always have the latest features and security patches without manual intervention.
-
Offline Capabilities: Certain features continue to work offline, with automatic synchronization when connectivity is restored.
-
Deep Linking: Custom protocol handlers (
zync://) allow other applications to deep-link directly into specific ZYNC features or conversations. -
Window Management: Multi-window support with persistent window state (position, size, maximization state) across application restarts.
| Feature | Description |
|---|---|
| Dashboard | Centralized overview of all team activities, recent projects, and quick actions |
| Workspace | Kanban-style project boards with drag-and-drop task management |
| Calendar | Team calendar with meeting scheduling and deadline tracking |
| Notes | Real-time collaborative note editor with rich text formatting |
| Tasks | Comprehensive task management with assignments, due dates, and priorities |
| Chat | Real-time messaging with @mentions, file attachments, and message reactions |
| Meet | Video conferencing integration for team meetings and pair programming |
| Activity Log | Detailed activity tracking with time logging and contribution graphs |
| Feature | Description |
|---|---|
| System Tray | Background operation with quick-access context menu |
| Auto-Updates | Automatic application updates with progress notifications |
| Native Notifications | OS-level notifications for messages, mentions, and reminders |
| Global Shortcuts | System-wide keyboard shortcuts for quick access |
| Deep Linking | zync:// protocol support for external integrations |
| Window Persistence | Remembers window position, size, and state across sessions |
| Splash Screen | Branded loading screen during application startup |
| Crash Reporting | Automatic crash report collection and submission |
| Settings Page | Native settings interface with download links for all platforms |
- Real-Time Presence: See who is online, away, or offline in real-time
- Collaborative Editing: Multiple users can edit the same document simultaneously
- Screen Sharing: Share your screen during video calls for pair programming
- File Sharing: Drag-and-drop file sharing with preview support
- @Mentions: Tag team members in conversations and notes for notifications
- Activity Graphs: Visual representation of team activity and contributions
- Team Management: Create and manage teams with role-based access control
- GitHub Integration: Connect GitHub accounts for repository management
- Git Commands: Built-in Git command reference and quick actions
- Repository Selector: Browse and manage connected repositories
- Task-Git Sync: Link tasks to Git branches, commits, and pull requests
- Contribution Graph: GitHub-style contribution visualization
| Component | Requirement |
|---|---|
| CPU | 1.6 GHz dual-core processor |
| RAM | 2 GB |
| Storage | 500 MB available disk space |
| Display | 1280 x 720 resolution |
| Network | Broadband internet connection (for real-time features) |
| Component | Specification |
|---|---|
| CPU | 2.0 GHz quad-core processor or better |
| RAM | 4 GB or more |
| Storage | 1 GB available disk space |
| Display | 1920 x 1080 resolution or higher |
| Network | High-speed internet connection (10 Mbps+) |
| Camera | Webcam (for video conferencing features) |
| Microphone | Built-in or external microphone (for audio features) |
| Platform | Versions | Architecture | Installer |
|---|---|---|---|
| Windows | Windows 10, Windows 11 | x64, arm64 | NSIS (.exe) |
| macOS | macOS 10.15 (Catalina) and later | x64, arm64 (Apple Silicon) | DMG (.dmg) |
| Linux | Ubuntu 18.04+, Fedora 32+, Debian 10+ | x64 | AppImage (.AppImage) |
Visit the Releases page to download the latest version for your platform.
- Download
ZYNC-Setup-x.x.x.exefrom the Releases page - Run the installer
- Choose the installation directory (default:
C:\Program Files\ZYNC) - Select whether to create desktop and Start Menu shortcuts
- Click "Install" to complete the installation
- Launch ZYNC from the desktop shortcut or Start Menu
Silent Installation (for system administrators):
# Install silently with default options
ZYNC-Setup-x.x.x.exe /S
# Install to a custom directory
ZYNC-Setup-x.x.x.exe /S /D=C:\CustomPath\ZYNC- Download
ZYNC-x.x.x.dmgfrom the Releases page - Open the DMG file
- Drag
ZYNC.appto theApplicationsfolder - Launch ZYNC from the Applications folder or Spotlight search
- If prompted about the application being from an unidentified developer:
- Go to System Preferences β Security & Privacy
- Click "Open Anyway"
Installation via Homebrew (coming soon):
# Install via Homebrew Cask
brew install --cask zync- Download
ZYNC-x.x.x.AppImagefrom the Releases page - Make the file executable:
chmod +x ZYNC-x.x.x.AppImage
- Run the application:
./ZYNC-x.x.x.AppImage
Desktop Integration:
# Install AppImageLauncher for desktop integration
# Then double-click the AppImage to integrate it into your desktop
sudo apt install appimagelauncher| Tool | Version | Purpose |
|---|---|---|
| Node.js | 18.x or later | JavaScript runtime for building and running |
| npm | 9.x or later | Package manager for installing dependencies |
| Git | 2.x or later | Version control for source code management |
| Python | 3.x | Required by some native Node.js modules |
| Visual Studio Build Tools | 2019+ (Windows only) | Required for compiling native modules on Windows |
| Xcode Command Line Tools | (macOS only) | Required for compiling native modules on macOS |
# Step 1: Clone the repository from GitHub
# This creates a local copy of the source code on your machine
git clone https://github.com/ChitkulLakshya/Zync.git
# Step 2: Navigate into the project directory
# All subsequent commands should be run from this directory
cd Zync
# Step 3: Install all project dependencies
# This installs both production and development dependencies
# defined in package.json. The installation may take several
# minutes depending on your internet connection speed.
npm install
# Step 4: Create a local environment file
# Copy the example environment file and fill in your own values
# for the Firebase configuration and API URLs
cp .env.example .env
# Step 5: Verify the installation
# Run the TypeScript compiler to check for any type errors
npx tsc --noEmit# Start the application in development mode
# This runs both the Vite dev server and Electron concurrently
npm run electron:dev
# Alternatively, run just the web application without Electron
# Useful for frontend development and testing
npm run dev
# Run with verbose logging enabled
# This provides detailed output for debugging purposes
ELECTRON_ENABLE_LOGGING=1 npm run electron:devZync/
βββ .github/ # GitHub-specific configuration files
β βββ workflows/ # GitHub Actions CI/CD workflows
β β βββ electron-build.yml # Automated build pipeline for all platforms
β β βββ release.yml # Automated release pipeline
β β βββ codeql.yml # Security analysis workflow
β βββ dependabot.yml # Automated dependency update configuration
β
βββ build/ # Build resources for electron-builder
β βββ icons/ # Application icons for all platforms
β βββ icon.ico # Windows icon (256x256, multi-size ICO)
β βββ icon.icns # macOS icon (512x512, Apple Icon format)
β βββ icon.png # Linux icon (512x512, PNG format)
β
βββ docs/ # Developer documentation
β βββ ARCHITECTURE.md # System architecture documentation
β βββ DEVELOPMENT.md # Development setup guide
β βββ DEPLOYMENT.md # Deployment and release guide
β
βββ electron/ # Electron main process source code
β βββ assets/ # Static assets for the Electron app
β β βββ icons.ts # Base64-encoded SVG icons
β β βββ platform-logos.ts # Base64-encoded platform logos
β β βββ sounds.ts # Base64-encoded notification sounds
β β βββ splash.ts # Splash screen resources
β β
β βββ config/ # Configuration modules
β β βββ constants.ts # Application-wide constants
β β βββ csp.ts # Content Security Policy configuration
β β βββ defaults.ts # Default configuration values
β β βββ permissions.ts # Permission handler configuration
β β βββ security.ts # Security policy configuration
β β
β βββ interfaces/ # TypeScript interface definitions
β β βββ config.ts # Configuration interfaces
β β βββ ipc.ts # IPC message interfaces
β β βββ services.ts # Service interfaces
β β βββ settings.ts # Settings interfaces
β β βββ updater.ts # Auto-updater interfaces
β β βββ window.ts # Window management interfaces
β β
β βββ main/ # Main process modules
β β βββ crash-reporter.ts # Crash reporting service
β β βββ deep-link.ts # Deep linking handler
β β βββ ipc-handlers.ts # IPC event handlers
β β βββ menu.ts # Application menu builder
β β βββ tray.ts # System tray manager
β β βββ window-state.ts # Window state persistence
β β
β βββ preload/ # Preload script modules
β β βββ types.d.ts # Type definitions for exposed APIs
β β
β βββ renderer/ # Renderer process helpers
β β
β βββ services/ # Background services
β β βββ auto-updater.ts # Auto-update service
β β
β βββ settings/ # Settings window
β β βββ about.html # About page
β β βββ about.js # About page logic
β β βββ animations.css # Settings page animations
β β βββ index.html # Settings page layout
β β βββ platform-utils.js # Platform detection utilities
β β βββ renderer.js # Settings page renderer
β β βββ shortcuts.html # Keyboard shortcuts reference
β β βββ shortcuts.js # Shortcuts page logic
β β βββ store.ts # Settings persistence
β β βββ style.css # Settings page styles
β β
β βββ splash/ # Splash screen
β β βββ index.html # Splash screen layout
β β βββ style.css # Splash screen styles
β β
β βββ types/ # Global type definitions
β β βββ electron-env.d.ts # Electron environment types
β β βββ global.d.ts # Global type augmentations
β β
β βββ utils/ # Utility modules
β β βββ clipboard.ts # Clipboard utilities
β β βββ fs-helpers.ts # File system helpers
β β βββ logger.ts # Logging utility
β β βββ network.ts # Network connectivity checker
β β βββ notifications.ts # Notification manager
β β βββ paths.ts # Platform-specific path resolver
β β βββ screenshot.ts # Screenshot utility
β β
β βββ main.ts # Main process entry point
β βββ preload.ts # Preload script entry point
β
βββ src/ # Frontend (renderer process) source code
β βββ api/ # API client modules
β βββ components/ # React components
β β βββ dashboard/ # Dashboard-specific components
β β βββ kibo-ui/ # Custom UI components
β β βββ landing/ # Landing page components
β β βββ layout/ # Layout components (navbar, etc.)
β β βββ notes/ # Note editor components
β β βββ ui/ # Shadcn/UI component library
β β βββ views/ # View components (pages within dashboard)
β β βββ workspace/ # Workspace components
β βββ hooks/ # Custom React hooks
β βββ lib/ # Library utilities
β βββ pages/ # Top-level page components
β βββ services/ # Frontend service modules
β βββ App.tsx # Root application component
β βββ index.css # Global styles
β βββ main.tsx # Application entry point
β βββ vite-env.d.ts # Vite type definitions
β
βββ tests/ # Test files
β βββ main/ # Main process tests
β βββ utils/ # Utility tests
β
βββ backend/ # Backend server source code
β
βββ .editorconfig # Editor configuration for consistent formatting
βββ .eslintrc.cjs # ESLint configuration
βββ .gitignore # Git ignore rules
βββ .prettierrc.json # Prettier formatting configuration
βββ CHANGELOG.md # Version changelog
βββ CODE_OF_CONDUCT.md # Community code of conduct
βββ CONTRIBUTING.md # Contribution guidelines
βββ LICENSE # MIT License
βββ SECURITY.md # Security policy
βββ electron-builder.yml # Electron Builder configuration
βββ index.html # Application entry HTML
βββ package.json # Project metadata and dependencies
βββ package-lock.json # Locked dependency versions
βββ tsconfig.json # Root TypeScript configuration
βββ tsconfig.app.json # Frontend TypeScript configuration
βββ tsconfig.electron.json # Electron TypeScript configuration
βββ tsconfig.node.json # Node.js TypeScript configuration
βββ vite.config.ts # Vite build configuration
| Variable | Description | Required | Default |
|---|---|---|---|
VITE_API_URL |
Backend API base URL | Yes | http://localhost:5000 |
VITE_FIREBASE_API_KEY |
Firebase API key | Yes | β |
VITE_FIREBASE_AUTH_DOMAIN |
Firebase auth domain | Yes | β |
VITE_FIREBASE_PROJECT_ID |
Firebase project ID | Yes | β |
VITE_FIREBASE_STORAGE_BUCKET |
Firebase storage bucket | Yes | β |
VITE_FIREBASE_MESSAGING_SENDER_ID |
Firebase messaging sender ID | Yes | β |
VITE_FIREBASE_APP_ID |
Firebase app ID | Yes | β |
VITE_FIREBASE_MEASUREMENT_ID |
Firebase measurement ID | No | β |
ELECTRON_ENABLE_LOGGING |
Enable verbose Electron logging | No | false |
# Build the Windows installer (.exe)
# This creates an NSIS installer in the dist_electron directory
npm run electron:build -- --win
# Build without code signing (for development/testing)
CSC_IDENTITY_AUTO_DISCOVERY=false npm run electron:build -- --win# Build the macOS DMG installer
# Note: Must be run on a macOS machine
npm run electron:build -- --mac
# Build for both Intel and Apple Silicon
npm run electron:build -- --mac --x64 --arm64# Build the Linux AppImage
npm run electron:build -- --linux
# Build for specific architectures
npm run electron:build -- --linux --x64The build process is configured through electron-builder.yml. Key settings:
- Output Directory:
dist_electron/β All build artifacts are placed here - Build Resources:
build/β Icons and other build-time resources - File Patterns: Only
electron/**/*andpackage.jsonare included - Windows: NSIS installer with optional installation directory selection
- macOS: DMG with drag-to-Applications layout
- Linux: AppImage for maximum compatibility
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β ZYNC Desktop Application β
β β
β ββββββββββββββββββββββββ ββββββββββββββββββββββββββββ β
β β Main Process β β Renderer Process β β
β β (electron/main.ts) β IPC β (Vite + React App) β β
β β βββββββββββΊβ β β
β β β’ Window Management β β β’ Dashboard β β
β β β’ System Tray β β β’ Workspace β β
β β β’ Auto-Updates β β β’ Chat β β
β β β’ Native Menus β β β’ Notes β β
β β β’ Deep Linking β β β’ Calendar β β
β β β’ Notifications β β β’ Tasks β β
β β β’ File System β β β’ Settings β β
β β β β β’ Meet β β
β ββββββββββββββββββββββββ ββββββββββββββββββββββββββββ β
β β β β
β β Preload Script β Web APIs β
β β (electron/preload.ts) β β
β β β β
β βΌ βΌ β
β ββββββββββββββββββββββββ ββββββββββββββββββββββββββββ β
β β Node.js APIs β β Backend Server β β
β β (File System, OS) β β (Express + MongoDB) β β
β ββββββββββββββββββββββββ ββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
The main process (electron/main.ts) is responsible for:
-
Application Lifecycle: Handling
ready,window-all-closed, andactivateevents to manage the application lifecycle correctly across all platforms. -
Window Management: Creating and managing the main application window and secondary windows (settings, about). Window state (position, size, maximized state) is persisted across sessions.
-
System Tray: Creating a system tray icon with a context menu that allows users to show/hide the window, check for updates, and quit.
-
Menu System: Building the application menu bar with keyboard shortcuts for common actions.
-
Auto-Updates: Checking for updates on startup and periodically, downloading updates in the background, and notifying users when updates are ready to install.
-
IPC Handlers: Handling messages from the renderer process for actions that require Node.js or native OS access.
The renderer process loads the ZYNC web application, which is built with:
- React β UI component library
- Vite β Build tool and development server
- React Router β Client-side routing
- TanStack Query β Data fetching and caching
- Firebase β Authentication and real-time database
- Tailwind CSS β Utility-first CSS framework
- Shadcn/UI β Component library built on Radix UI primitives
The preload script (electron/preload.ts) provides a secure bridge between
the main and renderer processes by exposing specific APIs through
contextBridge:
electron.downloadPlatform(platform)β Request platform-specific downloadselectron.openSettings()β Open the native settings windowelectron.on(channel, callback)β Listen for main process messagesversions.node()β Get Node.js versionversions.chrome()β Get Chrome versionversions.electron()β Get Electron version
Communication between processes uses Electron's IPC module with strict channel whitelisting:
| Channel | Direction | Purpose |
|---|---|---|
download-platform |
Renderer β Main | Request platform download |
open-settings |
Renderer β Main | Open settings window |
check-for-updates |
Renderer β Main | Trigger update check |
get-app-version |
Renderer β Main | Get application version |
fromMain |
Main β Renderer | Send messages to renderer |
-
Context Isolation: Enabled by default, preventing the renderer process from directly accessing Node.js APIs.
-
Node Integration: Disabled in the renderer process, requiring all Node.js access to go through the preload script.
-
Content Security Policy: Strict CSP headers prevent XSS attacks and unauthorized script execution.
-
Channel Whitelisting: Only pre-approved IPC channels are allowed, preventing arbitrary communication between processes.
-
Input Validation: All IPC messages are validated before processing to prevent injection attacks.
-
HTTPS Only: The application only loads content over HTTPS in production mode.
The ZYNC desktop application can be configured through the Settings page,
accessible from the application menu or by pressing Ctrl+, (Windows/Linux)
or Cmd+, (macOS).
Available settings include:
| Setting | Description | Default |
|---|---|---|
| Start on Login | Launch ZYNC when the system starts | Disabled |
| Minimize to Tray | Minimize to system tray instead of taskbar | Enabled |
| Auto-Update | Automatically download and install updates | Enabled |
| Notifications | Enable desktop notifications | Enabled |
| Theme | Application theme (Light, Dark, System) | System |
| Language | Application language | English |
| Shortcut | Action |
|---|---|
Ctrl/Cmd + N |
Create new note |
Ctrl/Cmd + , |
Open settings |
Ctrl/Cmd + Q |
Quit application |
Ctrl/Cmd + R |
Reload application |
Ctrl/Cmd + Shift + I |
Open Developer Tools |
Ctrl/Cmd + + |
Zoom in |
Ctrl/Cmd + - |
Zoom out |
Ctrl/Cmd + 0 |
Reset zoom |
F11 |
Toggle fullscreen |
# Run all tests
npm test
# Run tests with coverage report
npm run test:coverage
# Run only main process tests
npm test -- --testPathPattern=tests/main
# Run only utility tests
npm test -- --testPathPattern=tests/utils
# Run tests in watch mode during development
npm run test:watch# Clear the application cache and try again
# Windows
rmdir /s /q "%APPDATA%\ZYNC"
# macOS
rm -rf ~/Library/Application\ Support/ZYNC
# Linux
rm -rf ~/.config/ZYNCEnsure Visual Studio Build Tools are installed:
npm install --global windows-build-toolsThis usually indicates the web application URL is unreachable:
- Check your internet connection
- Verify the
VITE_API_URLenvironment variable is set correctly - Try running
npm run devseparately to verify the dev server works
# Enable debug mode with verbose logging
ELECTRON_ENABLE_LOGGING=1 DEBUG=* npm run electron:dev
# Open DevTools automatically on startup
npm run electron:dev -- --inspectLog files are stored in the following locations:
| Platform | Log Location |
|---|---|
| Windows | %APPDATA%\ZYNC\logs\ |
| macOS | ~/Library/Logs/ZYNC/ |
| Linux | ~/.config/ZYNC/logs/ |
We welcome contributions from the community! Please read our Contributing Guidelines before submitting a pull request.
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature - Make your changes and add tests
- Commit using conventional commits:
git commit -m "feat: add new feature" - Push to your fork:
git push origin feature/my-feature - Open a Pull Request
This project is licensed under the MIT License β see the LICENSE file for details.
- Electron β Framework for cross-platform desktop apps
- React β UI component library
- Vite β Next-generation frontend build tool
- Firebase β Backend-as-a-Service platform
- Tailwind CSS β Utility-first CSS framework
- Shadcn/UI β Beautifully designed components
- electron-builder β Complete solution for packaging Electron apps
Made with β€οΈ by the ZYNC Team