Cylence Project Documentation

Project Overview & Purpose

Cylence is a next-generation secure messenger designed for end-to-end encrypted communication. Unlike standard messaging apps, Cylence utilizes a unique "Vault" system where users manage their own cryptographic keys locally, ensuring that even if the server is compromised, message contents remain private.

Key Features:

End-to-End Encryption: Custom crypto engine handling message encryption/decryption on the client side.
Vault System: Secure local storage of identity keys and conversation secrets.
Device Registration: Multi-device support with secure vault syncing.
WebRTC Voice/Video: Encrypted real-time calling capabilities.
Rich Messaging: Support for reactions, link previews, and file attachments.

Coding Stack

Frontend

React 19 & Vite

Built with TypeScript for type safety. Uses Vite for blazing fast development and building.

React (Functional Components + Hooks)
CSS-in-JS (Inline styles & Vanilla CSS)
Linkify.js for URL parsing

Backend

Node.js & Express

A robust API layer built with Express and TypeScript.

Express.js (RESTful API)
JWT (Authentication)
Bcrypt (Password hashing)
pg (PostgreSQL client)

Database

PostgreSQL

Relational database used for storing users, conversations, and encrypted message metadata.

pgcrypto for UUID generation
Migration-based schema management

Services & Infrastructure

The application is designed to be containerized and easily deployed using Docker.

Core Services:

API Service: Node.js backend container managing business logic and WebRTC signaling.
Web Client: Frontend container serving the React application.
Database Service: PostgreSQL (or MariaDB) container for persistent storage.
WebRTC STUN/TURN: Google's STUN servers are used by default for NAT traversal.

Note: While the codebase currently utilizes PostgreSQL syntax (e.g., gen_random_uuid()), it can be adapted for MariaDB by updating the SQL migrations and the database driver.

Important Files

Backend

backend/src/server.ts: Entry point for the API.
backend/src/db.ts: Database connection pooling.
backend/src/auth/: Authentication routes and JWT logic.
backend/sql/schema.sql: Core database structure.
backend/migrations/: Incremental database updates.

Desktop (Frontend)

desktop/src/App.tsx: Main application logic and state management.
desktop/src/crypto/engine.ts: The E2EE encryption/decryption core.
desktop/src/crypto/vaultStorage.ts: Local storage management for secrets.
desktop/src/components/: All UI components (Sidebar, ChatWindow, etc.).

3rd Party Providers

Cylence leverages several external services to enhance the user experience:

Giphy API: Used for searching and sending GIFs in conversations.
Google STUN: stun:stun.l.google.com:19302 is used to facilitate WebRTC calls.
Gravatar / Profile APIs: Used for fetching user avatars based on email or identity.

How to Run the App

Prerequisites:

Node.js (v18 or higher)
PostgreSQL (running on port 5432)

Step 1: Start the Backend

cd backend
npm install
npm run dev

Step 2: Start the Desktop App

cd desktop
npm install
npm run dev

The application will be available at http://localhost:5173.

How to Make Changes

Updating the UI:

Navigate to desktop/src/components/. Most UI elements are split into specific components. Styles are primarily handled via inline React styles or App.css. The main layout is managed in App.tsx using a mobile-first responsive design.

Adding API Routes:

Create a new directory in backend/src/ (e.g., orders/).
Define your routes in orderRoutes.ts.
Register the route in backend/src/server.ts using app.use('/orders', orderRoutes).

Database Changes:

Add a new .sql file to backend/migrations/. The backend automatically runs these migrations on startup via runMigrations() in server.ts.

Managing API Keys & Env

All sensitive configuration is handled via .env files. Never commit these files to version control.

Backend (.env):

PORT=4000
DATABASE_URL=postgresql://user:pass@localhost:5432/db_name
JWT_SECRET=your-secure-secret-here
CORS_ORIGINS=http://localhost:5173

Frontend (.env):

VITE_API_BASE_URL=http://localhost:4000
VITE_GIPHY_API_KEY=your_giphy_key_here

To change keys, update the value in the respective .env file and restart the service.