BirdX Chat — self-hosted secure messaging
_{Real-time chat · Voice & video · E2EE · Admin panel · English & Persian (RTL)}

Quick start · Screenshots · Features · Deployment · Changelog · فارسی

---

Overview

This repository is the BirdX Chat application: client/ (React PWA) and server/ (Node.js API). Deploy it on your own domain for your team or community.

The marketing site lives in a separate repo: birdx-marketing (birdx.chat). See WORKSPACE.md for how to lay out both projects on disk.

Pre-built Windows/Android installers and iOS builds are part of the hosted BirdX product operated by iPmart Network. Self-hosters use the browser/PWA on their server URL.

Hosted BirdX (official)

Service	Description
birdx.chat	Official website, docs, downloads (private deployment)
app.birdx.chat	Official web app for BirdX users

Custom work (on request)

We also ship, outside this public repo:

• Branded marketing websites
• Windows / Android / iOS shell apps pointing at a chosen URL
• Store-ready package IDs and icons

Contact @birdx_app or GitHub Issues for dedicated builds.

---

Screenshots

_{Add or replace images under docs/screenshots/ (see README there). Until files exist, GitHub may show broken image placeholders.}

---

Quick start

git clone https://github.com/iPmartNetwork/BirdX.Chat.git
cd BirdX.Chat
npm install
cp .env.example .env   # your domain, TURN, VAPID, keys
npm run build
npm start

Linux one-liner:

bash <(curl -fsSL https://raw.githubusercontent.com/iPmartNetwork/BirdX.Chat/master/scripts/install.sh)

Interactive birdx-deploy menu: install, update, .env, database, logs, and optional coturn TURN. Re-run anytime: sudo birdx-deploy.

Serve over HTTPS on your hostname (e.g. https://chat.example.com). Default bootstrap admin: birdxchat (ADMIN_USERNAMES).

Development

Git (optional): To avoid cursoragent appearing as a GitHub contributor, turn off Cursor Settings → Agents → Attribution, then run bash scripts/setup-git-hooks.sh once per clone (strips Co-authored-by: Cursor from commit messages).

Command	Description
npm run dev	Client + API (local)
npm run dev:stop	Stop dev processes (Windows)
npm run build	Production client → client/dist/
npm start	API serves client + WebSocket

---

Features

Messaging

• Direct messages, groups, channels, saved messages
• Reactions, reply, edit, delete, forward, read receipts
• DM privacy: exact username lookup, DM policy, conversation requests, block list
• Files, voice, polls, stickers, scheduled messages, archived chats

Security

• E2EE for direct messages (X3DH + AES-256-GCM)
• TOTP 2FA and backup codes
• Encrypted storage at rest
• Rate limits and security event logging

Calls

• WebRTC voice/video and screen share
• Call history tab, group calls (mesh or optional SFU)
• TURN/STUN via .env

Admin (/admin)

• Role-based access (owner → user)
• Users, chats, files, audit, analytics, exports
• Broadcasts, moderation queue, server settings, DB backup UI
• Optional admin 2FA step-up

Integrations

• Webhooks, bot API, remote channel mirroring
• Branding API, EN/FA + RTL

---

Tech stack

React 19 · Vite 7 · Tailwind 3 · Express · Socket.IO · sql.js (SQLite) · WebRTC · PWA

---

Project structure (this repository)

BirdX.Chat/
├── client/       React web app (PWA)
├── server/       API, Socket.IO, migrations
├── deploy/nginx/ Example reverse-proxy configs
├── docs/         Documentation assets (e.g. README screenshots)
├── data/         Runtime DB & uploads (local, not in git)
└── scripts/      Install helpers

---

Configuration

Copy .env.example → .env. See comments for DM policy, uploads, retention, TURN, VAPID, and STORAGE_ENCRYPTION_KEY (do not change after first run).

Voice/video calls: set APP_TURN_URLS / APP_TURN_USERNAME / APP_TURN_CREDENTIAL for reliable audio on mobile and strict NATs. Group call behaviour is controlled by GROUP_CALL_MODE (mesh default, or sfu), GROUP_CALL_MIN_MEMBERS, and GROUP_CALL_MAX_PARTICIPANTS. If a reverse proxy or mobile (Capacitor) shell connects from a different origin, list allowed origins in APP_ALLOWED_ORIGINS (empty = allow any; session auth is always enforced).

Database tools: npm --prefix server run db:help

---

Deployment

1. npm install && npm run build
2. Configure Nginx — deploy/README.md, deploy/nginx/
3. npm start or systemd
4. Point your domain with TLS; configure TURN for calls

Self-hosters do not need the BirdX marketing site or store installers unless they build their own landing page and native shells (custom project).

---

Security

• Keep .env and backups private
• HTTPS only in production
• Enable 2FA for admins
• Plan TURN for NAT traversal

---

Support

Bugs & features	GitHub Issues
BirdX announcements	@birdx_app
Custom site / mobile apps	Telegram or Issues (commercial / dedicated setup)

---

Credits

Developed by iPmart Network.

Thanks to Mr. Pouya Khalili (@bllackbull) for the original open-source vision. BirdX Chat is an independent codebase.

---

License

MIT