{"id":24463347,"url":"https://github.com/mohamedayassin/peerlink","last_synced_at":"2026-02-11T03:07:28.281Z","repository":{"id":273133860,"uuid":"918798060","full_name":"MohamedAYassin/PeerLink","owner":"MohamedAYassin","description":"A TypeScript React Website Made to Swiftly \u0026 Securely Share Files","archived":false,"fork":false,"pushed_at":"2025-01-18T22:22:14.000Z","size":3171,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T07:11:31.813Z","etag":null,"topics":["file-sharing","file-upload","p2p","peer-to-peer","peerjs","react","typescript","typescript-react","vite","vitejs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MohamedAYassin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-18T21:59:26.000Z","updated_at":"2025-01-18T22:35:35.000Z","dependencies_parsed_at":"2025-01-18T23:17:17.134Z","dependency_job_id":"89dd0637-57c5-4c34-abea-be6a61ab2a0f","html_url":"https://github.com/MohamedAYassin/PeerLink","commit_stats":null,"previous_names":["mohamedayassin/peerlink"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MohamedAYassin%2FPeerLink","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MohamedAYassin%2FPeerLink/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MohamedAYassin%2FPeerLink/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MohamedAYassin%2FPeerLink/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MohamedAYassin","download_url":"https://codeload.github.com/MohamedAYassin/PeerLink/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248675424,"owners_count":21143768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["file-sharing","file-upload","p2p","peer-to-peer","peerjs","react","typescript","typescript-react","vite","vitejs"],"created_at":"2025-01-21T05:11:17.661Z","updated_at":"2026-02-11T03:07:28.273Z","avatar_url":"https://github.com/MohamedAYassin.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PeerLink\n\n![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)\n![License](https://img.shields.io/badge/license-MIT-green.svg)\n![Open Source](https://img.shields.io/badge/Open%20Source-Yes-brightgreen.svg)\n![Status](https://img.shields.io/badge/status-production--ready-brightgreen.svg)\n![Native](https://img.shields.io/badge/native-C%2B%2B-orange.svg)\n\n\u003e **A high-performance, open-source distributed file sharing platform engineered for scale.**\n\n---\n\n## Table of Contents\n\n- [Introduction](#-introduction)\n- [System Architecture](#-system-architecture)\n  - [Microservices \u0026amp; Modularity](#microservices--modularity)\n  - [The Cluster Protocol](#the-cluster-protocol)\n  - [Native Performance Layer](#native-performance-layer)\n- [Tech Stack](#-tech-stack)\n- [Getting Started](#-getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n- [Configuration](#-configuration)\n- [Running the Application](#-running-the-application)\n- [Contributing](#-contributing)\n\n---\n\n## Introduction\n\nPeerLink is not just a file transfer tool; it is a sophisticated distributed system designed to handle high-throughput data transfer across a clustered environment. Built with a \"performance-first\" mindset, it leverages a microservices-inspired architecture to ensure that no single point of failure exists.\n\nWhether you are running a single instance or a fleet of nodes across different continents, PeerLink's intelligent routing layer ensures your data gets where it needs to go—instantly.\n\n---\n\n## Showcase\n\n![PeerLink Arch](showcase/arch.png)\n\n![Demo](showcase/demo.gif)\n\n---\n\n## System Architecture\n\nPeerLink moves away from the traditional monolithic server model. Instead, it operates as a collection of intelligent **Nodes** that form a cooperative cluster. **These nodes are fully decoupled and can run on separate physical machines, different cloud regions, or distinct containers, creating a truly distributed network.**\n\n### Microservices \u0026 Modularity\n\nThe backend is strictly decoupled into autonomous services, each responsible for a specific domain. This modularity allows for independent scaling and maintenance.\n\n**Application Services:**\n\n* **Cluster Service**: The brain of the operation. It manages leader election, node discovery, and inter-node routing.\n* **Session Service**: Handles user state, authentication, and connection persistence across the cluster.\n* **Node Service**: Manages the lifecycle of individual worker nodes, performing health checks and self-healing routines.\n* **Stats Service**: Aggregates real-time metrics from all nodes to provide a holistic view of system health.\n\n**Infrastructure Services:**\n\n* **PostgreSQL Database**: Operates as a completely separate, dedicated service for persistent data storage, ensuring data integrity independent of application nodes.\n* **Redis**: Runs as a standalone high-performance service handling caching, Pub/Sub messaging, and cluster coordination.\n\n### The Cluster Protocol\n\nHow do nodes talk to each other? We built a custom event-driven backbone using **Redis Pub/Sub**.\n\n1. **Leader Election**: Nodes automatically elect a \"Master\" node to handle complex routing decisions and cluster-wide synchronization.\n2. **Smart Routing**: If User A (on Node 1) sends a file to User B (on Node 2), the system identifies the target node and routes the data stream internally. The users never know they are on different servers.\n3. **State Consistency**: All session states are persisted in PostgreSQL but cached in Redis for millisecond-level access speeds.\n4. **Dynamic Scaling**: The system supports hot-swappable nodes. As you spin up new Docker containers, the frontend automatically discovers them via Redis, enabling seamless horizontal scaling with zero downtime.\n\n### Native Performance Layer\n\nJavaScript is fast, but C++ is faster. For CPU-intensive tasks, we bypass the Node.js event loop and drop down to bare metal.\n\n* **`net_io` Addon**: A custom C++ N-API module built specifically for PeerLink.\n* **SIMD Checksums**: We utilize AVX/SSE instructions to calculate file integrity hashes 400% faster than standard crypto libraries.\n* **XOR Cipher**: Real-time stream obfuscation with zero latency overhead.\n\n---\n\n## Tech Stack\n\n| Component           | Technology   | Description                                        |\n| ------------------- | ------------ | -------------------------------------------------- |\n| **Frontend**  | React + Vite | Ultra-fast UI rendering and bundling.              |\n| **Styling**   | Tailwind CSS | Utility-first CSS for consistent design.           |\n| **Runtime**   | Node.js      | Asynchronous event-driven JavaScript runtime.      |\n| **Language**  | TypeScript   | Strict typing for robust, error-free code.         |\n| **Transport** | Socket.IO    | Real-time bidirectional event-based communication. |\n| **Database**  | PostgreSQL   | Relational data integrity for sessions and nodes.  |\n| **ORM**       | Prisma       | Type-safe database access and schema management.   |\n| **Cache/Msg** | Redis        | High-performance caching and Pub/Sub messaging.    |\n| **Native**    | C++ (N-API)  | Low-level optimization for critical paths.         |\n\n---\n\n## Getting Started\n\n### Prerequisites\n\nEnsure your environment is ready for high-performance computing.\n\n* **Node.js**: v18.0.0 or higher\n* **PostgreSQL**: v14+\n* **Redis**: v6+ (Essential for Cluster Mode)\n* **Build Tools**: Python 3 \u0026 C++ compiler (Visual Studio Build Tools on Windows, `build-essential` on Linux) for compiling the native addon.\n\n### Installation\n\n1. **Clone the Repository**\n\n   ```bash\n   git clone https://github.com/yourusername/peerlink.git\n   cd peerlink\n   ```\n2. **Backend Setup**\n\n   ```bash\n   cd backend\n   npm install\n\n   # Configure Environment\n   cp .env.example .env\n   # EDIT .env with your DB/Redis credentials!\n\n   # Initialize Database\n   npm run prisma:generate\n   npm run prisma:push\n   ```\n3. **Frontend Setup**\n\n   ```bash\n   cd frontend\n   npm install\n   cp .env.example .env\n   ```\n\n---\n\n## Configuration\n\nPeerLink is designed to be flexible. Control every aspect of the system via environment variables.\n\n### Backend Configuration (`backend/.env`)\n\n#### Database\n\n| Variable         | Default              | Description                       |\n| ---------------- | -------------------- | --------------------------------- |\n| `DATABASE_URL` | `postgresql://...` | Connection string for PostgreSQL. |\n\n#### Server \u0026 Cluster\n\n| Variable          | Default         | Description                                                  |\n| ----------------- | --------------- | ------------------------------------------------------------ |\n| `PORT`          | `5000`        | The port the server listens on.                              |\n| `NODE_ENV`      | `development` | Environment mode (`development` or `production`).        |\n| `NODE_HOSTNAME` | `localhost`   | Hostname for this specific node (used in cluster discovery). |\n| `NODE_PORT`     | `5000`        | Port for this specific node.                                 |\n\n#### Redis (Caching \u0026 Pub/Sub)\n\n| Variable                  | Default       | Description                           |\n| ------------------------- | ------------- | ------------------------------------- |\n| `REDIS_HOST`            | `localhost` | Redis server hostname.                |\n| `REDIS_PORT`            | `6379`      | Redis server port.                    |\n| `REDIS_PASSWORD`        | -             | Redis password (leave empty if none). |\n| `REDIS_DB`              | `0`         | Redis database index.                 |\n| `REDIS_MAX_RETRIES`     | `3`         | Max connection retries.               |\n| `REDIS_RETRY_DELAY`     | `100`       | Delay between retries (ms).           |\n| `REDIS_CONNECT_TIMEOUT` | `10000`     | Connection timeout (ms).              |\n\n#### Redis TTL (Time-To-Live)\n\n| Variable                  | Default   | Description                                |\n| ------------------------- | --------- | ------------------------------------------ |\n| `TTL_CLIENT_SESSION`    | `3600`  | Session duration in seconds (1 hour).      |\n| `TTL_SHARE_SESSION`     | `86400` | Share link duration in seconds (24 hours). |\n| `TTL_UPLOAD_STATE`      | `7200`  | Upload state retention (2 hours).          |\n| `TTL_RATE_LIMIT_WINDOW` | `60`    | Rate limit window (1 minute).              |\n| `TTL_HEARTBEAT`         | `300`   | Node heartbeat expiration (5 minutes).     |\n\n#### Security \u0026 Rate Limiting\n\n| Variable                                     | Default                   | Description                       |\n| -------------------------------------------- | ------------------------- | --------------------------------- |\n| `CORS_ORIGIN`                              | `http://localhost:5173` | Allowed frontend origin.          |\n| `RATE_LIMIT_UPLOADS_PER_MINUTE`            | `100`                   | Max uploads per user/min.         |\n| `RATE_LIMIT_DOWNLOADS_PER_MINUTE`          | `100`                   | Max downloads per user/min.       |\n| `RATE_LIMIT_WEBSOCKET_MESSAGES_PER_MINUTE` | `1000`                  | Max socket messages per user/min. |\n\n#### File Transfer\n\n| Variable                     | Default        | Description                          |\n| ---------------------------- | -------------- | ------------------------------------ |\n| `MAX_FILE_SIZE`            | `1073741824` | Max file size in bytes (1GB).        |\n| `CHUNK_SIZE`               | `16384`      | Size of each file chunk (16KB).      |\n| `MAX_CONCURRENT_UPLOADS`   | `10`         | Max simultaneous uploads per node.   |\n| `MAX_CONCURRENT_DOWNLOADS` | `10`         | Max simultaneous downloads per node. |\n| `MAX_CONCURRENT_TRANSFERS` | `5`          | Max active transfers per user.       |\n| `ACK_TIMEOUT_MS`           | `10000`      | Timeout for chunk acknowledgement.   |\n| `MAX_RETRIES`              | `3`          | Max retries for failed chunks.       |\n\n#### Performance \u0026 Features\n\n| Variable               | Default  | Description                               |\n| ---------------------- | -------- | ----------------------------------------- |\n| `USE_NATIVE_ADDON`   | `true` | Enable C++ SIMD optimizations.            |\n| `USE_REDIS`          | `true` | Enable Redis (Required for Cluster).      |\n| `USE_CLUSTER`        | `true` | Enable distributed cluster mode.          |\n| `ENABLE_COMPRESSION` | `true` | Enable WebSocket per-message compression. |\n| `ENABLE_METRICS`     | `true` | Enable Prometheus-style metrics.          |\n\n---\n\n### Frontend Configuration (`frontend/.env`)\n\n#### API \u0026 Network\n\n| Variable             | Default                   | Description                  |\n| -------------------- | ------------------------- | ---------------------------- |\n| `VITE_BACKEND_URL` | `http://localhost:5000` | URL of the backend API.      |\n| `VITE_WS_URL`      | `http://localhost:5000` | URL of the WebSocket server. |\n\n#### Cluster Configuration\n\n| Variable               | Default   | Description                                                 |\n| ---------------------- | --------- | ----------------------------------------------------------- |\n| `VITE_USE_CLUSTER`   | `false` | Enable dynamic load balancing and node discovery.           |\n| `VITE_CLUSTER_NODES` | `...`   | Initial list of backend nodes for bootstrapping connection. |\n\n#### Transfer Settings\n\n| Variable                    | Default   | Description                    |\n| --------------------------- | --------- | ------------------------------ |\n| `VITE_CHUNK_SIZE`         | `65536` | Chunk size for uploads (64KB). |\n| `VITE_UPLOAD_CONCURRENCY` | `6`     | Parallel chunk uploads.        |\n\n#### Socket Settings\n\n| Variable                               | Default  | Description                      |\n| -------------------------------------- | -------- | -------------------------------- |\n| `VITE_SOCKET_RECONNECTION_DELAY`     | `1000` | Initial reconnection delay (ms). |\n| `VITE_SOCKET_RECONNECTION_DELAY_MAX` | `5000` | Max reconnection delay (ms).     |\n| `VITE_SOCKET_RECONNECTION_ATTEMPTS`  | `5`    | Max reconnection attempts.       |\n\n---\n\n## Running the Application\n\n### Development Mode\n\nRun the full stack with hot-reloading enabled.\n\n**Terminal 1 (Backend):**\n\n```bash\ncd backend\nnpm run dev\n```\n\n**Terminal 2 (Frontend):**\n\n```bash\ncd frontend\nnpm run dev\n```\n\n### Production Build\n\nCompile the TypeScript code and build the C++ native addons for maximum performance.\n\n```bash\n# Build Backend (includes C++ compilation)\ncd backend\nnpm run build\nnpm run copy-native\nnpm start\n\n# Build Frontend\ncd frontend\nnpm run build\n```\n\n---\n\n## Docker Deployment\n\nPeerLink is fully containerized and ready for production deployment using Docker Compose.\n\n### Prerequisites\n\n* **Docker** and **Docker Compose** installed.\n\n### Running with Docker\n\n1. **Build and Start Services**\n\n   ```bash\n   docker-compose up --build\n   ```\n\n   This will start:\n\n   * **Frontend**: `http://localhost`\n   * **Backend**: `http://localhost:5000`\n   * **PostgreSQL**: Port 5432 (Separate Service)\n   * **Redis**: Port 6379 (Separate Service)\n2. **Scale Up (Hot Swapping)**\n   To demonstrate dynamic scaling, you can spin up multiple backend nodes:\n\n   ```bash\n   docker-compose up -d --scale backend=3\n   ```\n\n   The frontend will automatically discover the new nodes via Redis.\n\n---\n\n## Contributing\n\nWe welcome contributions from the community. However, to maintain the high stability standards of PeerLink, we have strict guidelines.\n\n### Reporting Bugs\n\nIf you encounter an issue, **you must provide a complete reproduction path**. Vague reports like \"it doesn't work\" will be closed immediately without review.\n\n**Required Format for Issues:**\n\n1. **Environment**: OS, Node Version, Browser.\n2. **Configuration**: Are you using Cluster Mode? Redis? Native Addons?\n3. **Steps to Reproduce**: A numbered list of exact actions taken.\n4. **Logs**: Paste the full error stack trace from the backend terminal and browser console.\n\n### Feature Requests\n\nHave an idea to make PeerLink even faster? Open a Pull Request! Please ensure your code follows the existing modular structure and includes proper typing.\n\n---\n\n*Built with precision. Engineered for speed.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmohamedayassin%2Fpeerlink","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmohamedayassin%2Fpeerlink","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmohamedayassin%2Fpeerlink/lists"}