Documentation

Everything you need to build, deploy, and self-host ZeroZone.

1What is ZeroZone

ZeroZone is a self-hosted, open-source real-time communication platform. It combines text chat, voice/video calls, and community management into a single deployable unit. You own the server, the data, and the infrastructure.

Real-Time Messaging

Instant message delivery with typing indicators, reactions, pinning, and file sharing.

Voice & Video

1:1 calls and zone voice channels powered by LiveKit with speaking detection.

Communities

Zones with text and voice channels, role-based access, and invite systems.

Privacy First

Messages encrypted at rest, no ads, no tracking, fully self-hostable.

2Tech Stack

Next.js 16

Frontend (App Router)

React 19

UI Library

TypeScript

Language

Express 5

Backend API

Socket.io 4

Real-Time Events

Prisma

ORM

PostgreSQL

Database

LiveKit

Voice & Video

Tailwind CSS

Styling

Zustand

Client State

React Query

Server State

Zod

Validation

3Architecture

ZeroZone follows a monorepo structure with four packages:

zerozone/
├── apps/
│   ├── frontend/        # Next.js 16 (App Router)
│   └── backend/         # Express 5 + Socket.io + Prisma
├── packages/
│   ├── components/      # Shared shadcn/ui components
│   ├── lib/             # Shared utilities and types
│   └── types/           # TypeScript type definitions
└── desktop/             # Electron wrapper

Frontend communicates with the backend via REST API for CRUD operations and Socket.io for real-time events (messages, presence, typing, calls).

Authentication uses JWT tokens stored in HTTP-only cookies. The middleware protects all /zone/*, /settings/*, and /dashboard/* routes.

Voice/Video uses LiveKit for WebRTC infrastructure. 1:1 DM calls and zone voice channels both go through LiveKit rooms with tokens generated by the backend.

4Zones & Channels

Zones are communities (like servers). Each zone contains text and voice channels, members with roles, and an invite system.

Text Channels

Persistent message threads within a zone. Support file uploads, pinning, and emoji reactions.

Voice Channels

LiveKit-powered voice rooms. Click to join, see who's speaking, mute/deafen controls.

Roles

OWNER, ADMIN, and MEMBER roles control who can manage channels, kick members, or edit zone settings.

Invites

Generate invite links with 7-day expiry. Members join via /zone/invite/[code].

5Direct Messages

1:1 conversations between friends. Messages are encrypted at rest and decrypted on retrieval.

Typing indicators with 3-second timeout
Message editing and soft-deletion
Pin important messages
File/image attachments (2MB limit)
Infinite scroll with cursor-based pagination (50 per page)
Emoji, GIF, and sticker pickers
Integrated voice calling via LiveKit

6Voice & Video

Two voice systems powered by LiveKit:

1:1 DM Calls

Private voice/video calls between two friends. Floating call overlay with accept/reject/cancel. Reconnection support with 10-second grace period.

Zone Voice Channels

Discord-style voice channels. Click to join, see participants in real-time, mute/deafen controls, speaking detection via Web Audio API.

7Friends System

Friend relationships power DM access. The flow:

Search for a user by username
Send a friend request (requires verified email)
Other user accepts or rejects
Once friends, you can start DM chats and call each other

Users can also block others, which removes existing friendships and prevents future requests. Online status is tracked via Socket.io heartbeat.

8Authentication API

All auth endpoints are under /auth. JWT tokens are set as HTTP-only cookies.

POST

/auth/register

POST

/auth/login

POST

/auth/google

GET

/auth/me

Get current authenticated user profile

POST

/auth/logout

Clear JWT cookie

POST

/auth/resend-email

Resend email verification OTP

POST

/auth/verify-email

Verify email with 6-digit OTP code

9Zones API

Zone management endpoints under /zones.

GET

/zones/

Get all zones the user belongs to

POST

/zones/

Create a new zone (auto-creates #general channel)

GET

/zones/:id/channels

Get all channels in a zone

POST

/zones/:id/channels

Create a new text or voice channel

GET

/zones/:id/members

Get all members with roles

POST

/zones/:id/members

Add users to the zone

POST

/zones/:id/invites

Generate an invite link (7-day expiry)

POST

/zones/:id/leave

Leave the zone (owners cannot leave)

PATCH

/zones/:id

Update zone name or avatar (owner/admin)

DELETE

/zones/:id

Delete zone entirely (owner only)

10Messages API

Chat and message endpoints under /chats.

GET

/chats/

Get all DM chats with last message

POST

/chats/start

Start or resume a DM with a friend

GET

/chats/:id/messages

Get messages (cursor-based, 50 per page)

POST

/chats/:id/upload

Upload an image to a chat (2MB limit)

PATCH

/chats/messages/:id

Edit a message

PATCH

/chats/messages/:id/pin

Toggle pin on a message

DELETE

/chats/messages/:id

Soft-delete a message (sender only)

11WebSocket Events

Socket.io events for real-time communication. Connection authenticates via JWT from the token cookie.

Messaging

emit private-message { chatPublicId, text?, fileUrl? }

emit chat:typing { chatPublicId, isTyping }

listen private-message → incoming message

listen message:updated / message:deleted / message:pinned

Friends & Presence

emit presence:heartbeat

listen user:online / user:offline

listen friend:request / friend:accepted / friend:removed

Voice Calls

emit call:user { toUserId, chatPublicId }

emit call:accept / call:reject / call:end

listen incoming:call / call:accepted / call:ended

emit channel:join-call { channelPublicId }

listen zone:voice-presence → participant list

Zones

emit zone:join / zone:leave { zonePublicId }

listen zone:presence / zone:members-updated / zone:channels-updated

12Prerequisites

Node.js 20 or later
pnpm 10.20.0 (or use corepack enable)
PostgreSQL database
LiveKit server (for voice/video)

13Installation

bash

# Clone the repository
git clone https://github.com/DevMuhammed3/ZeroZone.git
cd ZeroZone

# Enable pnpm via corepack
corepack enable

# Install dependencies
pnpm install

# Set up environment variables
cp apps/backend/.env.example apps/backend/.env
cp apps/frontend/.env.local.example apps/frontend/.env.local

# Run database migrations
cd apps/backend
pnpm prisma migrate dev

# Start development servers
pnpm dev

14Environment Variables

Backend (apps/backend/.env):

DATABASE_URL=postgresql://...

JWT_SECRET=your-secret-key

PORT=4000

BASE_URL=http://localhost:4000

ZEROZONE_ALLOWED_ORIGINS=http://localhost:3000

COOKIE_DOMAIN=localhost

LIVEKIT_URL=wss://your-livekit-server

LIVEKIT_API_KEY=...

LIVEKIT_API_SECRET=...

Frontend (apps/frontend/.env.local):

NEXT_PUBLIC_API_URL=http://localhost:4000

NEXT_PUBLIC_GOOGLE_CLIENT_ID=...

15Deployment

Build all packages for production:

bash

# Build everything
pnpm build

# The frontend outputs to apps/frontend/.next (standalone mode)
# The backend compiles to apps/backend/dist/

The frontend is configured with output: 'standalone' for containerized deployments. The backend runs via tsx watch in development and compiles to JavaScript for production.

For the Electron desktop app, see the desktop/ directory. It wraps the frontend in an Electron shell.

Questions? Open an issue on GitHub.

Documentation

Everything you need to build, deploy, and self-host ZeroZone.

1What is ZeroZone

Real-Time Messaging

Instant message delivery with typing indicators, reactions, pinning, and file sharing.

Voice & Video

1:1 calls and zone voice channels powered by LiveKit with speaking detection.

Communities

Zones with text and voice channels, role-based access, and invite systems.

Privacy First

Messages encrypted at rest, no ads, no tracking, fully self-hostable.

2Tech Stack

Next.js 16

Frontend (App Router)

React 19

UI Library

TypeScript

Language

Express 5

Backend API

Socket.io 4

Real-Time Events

Prisma

ORM

PostgreSQL

Database

LiveKit

Voice & Video

Tailwind CSS

Styling

Zustand

Client State

React Query

Server State

Zod

Validation

3Architecture

ZeroZone follows a monorepo structure with four packages:

zerozone/
├── apps/
│   ├── frontend/        # Next.js 16 (App Router)
│   └── backend/         # Express 5 + Socket.io + Prisma
├── packages/
│   ├── components/      # Shared shadcn/ui components
│   ├── lib/             # Shared utilities and types
│   └── types/           # TypeScript type definitions
└── desktop/             # Electron wrapper

Frontend communicates with the backend via REST API for CRUD operations and Socket.io for real-time events (messages, presence, typing, calls).

Authentication uses JWT tokens stored in HTTP-only cookies. The middleware protects all /zone/*, /settings/*, and /dashboard/* routes.

Voice/Video uses LiveKit for WebRTC infrastructure. 1:1 DM calls and zone voice channels both go through LiveKit rooms with tokens generated by the backend.

4Zones & Channels

Zones are communities (like servers). Each zone contains text and voice channels, members with roles, and an invite system.

Text Channels

Persistent message threads within a zone. Support file uploads, pinning, and emoji reactions.

Voice Channels

LiveKit-powered voice rooms. Click to join, see who's speaking, mute/deafen controls.

Roles

OWNER, ADMIN, and MEMBER roles control who can manage channels, kick members, or edit zone settings.

Invites

Generate invite links with 7-day expiry. Members join via /zone/invite/[code].

5Direct Messages

1:1 conversations between friends. Messages are encrypted at rest and decrypted on retrieval.

Typing indicators with 3-second timeout
Message editing and soft-deletion
Pin important messages
File/image attachments (2MB limit)
Infinite scroll with cursor-based pagination (50 per page)
Emoji, GIF, and sticker pickers
Integrated voice calling via LiveKit

6Voice & Video

Two voice systems powered by LiveKit:

1:1 DM Calls

Private voice/video calls between two friends. Floating call overlay with accept/reject/cancel. Reconnection support with 10-second grace period.

Zone Voice Channels

Discord-style voice channels. Click to join, see participants in real-time, mute/deafen controls, speaking detection via Web Audio API.

7Friends System

Friend relationships power DM access. The flow:

Search for a user by username
Send a friend request (requires verified email)
Other user accepts or rejects
Once friends, you can start DM chats and call each other

Users can also block others, which removes existing friendships and prevents future requests. Online status is tracked via Socket.io heartbeat.

8Authentication API

All auth endpoints are under /auth. JWT tokens are set as HTTP-only cookies.

POST

/auth/register

POST

/auth/login

POST

/auth/google

GET

/auth/me

Get current authenticated user profile

POST

/auth/logout

Clear JWT cookie

POST

/auth/resend-email

Resend email verification OTP

POST

/auth/verify-email

Verify email with 6-digit OTP code

9Zones API

Zone management endpoints under /zones.

GET

/zones/

Get all zones the user belongs to

POST

/zones/

Create a new zone (auto-creates #general channel)

GET

/zones/:id/channels

Get all channels in a zone

POST

/zones/:id/channels

Create a new text or voice channel

GET

/zones/:id/members

Get all members with roles

POST

/zones/:id/members

Add users to the zone

POST

/zones/:id/invites

Generate an invite link (7-day expiry)

POST

/zones/:id/leave

Leave the zone (owners cannot leave)

PATCH

/zones/:id

Update zone name or avatar (owner/admin)

DELETE

/zones/:id

Delete zone entirely (owner only)

10Messages API

Chat and message endpoints under /chats.

GET

/chats/

Get all DM chats with last message

POST

/chats/start

Start or resume a DM with a friend

GET

/chats/:id/messages

Get messages (cursor-based, 50 per page)

POST

/chats/:id/upload

Upload an image to a chat (2MB limit)

PATCH

/chats/messages/:id

Edit a message

PATCH

/chats/messages/:id/pin

Toggle pin on a message

DELETE

/chats/messages/:id

Soft-delete a message (sender only)

11WebSocket Events

Socket.io events for real-time communication. Connection authenticates via JWT from the token cookie.

Messaging

emit private-message { chatPublicId, text?, fileUrl? }

emit chat:typing { chatPublicId, isTyping }

listen private-message → incoming message

listen message:updated / message:deleted / message:pinned

Friends & Presence

emit presence:heartbeat

listen user:online / user:offline

listen friend:request / friend:accepted / friend:removed

Voice Calls

emit call:user { toUserId, chatPublicId }

emit call:accept / call:reject / call:end

listen incoming:call / call:accepted / call:ended

emit channel:join-call { channelPublicId }

listen zone:voice-presence → participant list

Zones

emit zone:join / zone:leave { zonePublicId }

listen zone:presence / zone:members-updated / zone:channels-updated

12Prerequisites

Node.js 20 or later
pnpm 10.20.0 (or use corepack enable)
PostgreSQL database
LiveKit server (for voice/video)

13Installation

bash

# Clone the repository
git clone https://github.com/DevMuhammed3/ZeroZone.git
cd ZeroZone

# Enable pnpm via corepack
corepack enable

# Install dependencies
pnpm install

# Set up environment variables
cp apps/backend/.env.example apps/backend/.env
cp apps/frontend/.env.local.example apps/frontend/.env.local

# Run database migrations
cd apps/backend
pnpm prisma migrate dev

# Start development servers
pnpm dev

14Environment Variables

Backend (apps/backend/.env):

DATABASE_URL=postgresql://...

JWT_SECRET=your-secret-key

PORT=4000

BASE_URL=http://localhost:4000

ZEROZONE_ALLOWED_ORIGINS=http://localhost:3000

COOKIE_DOMAIN=localhost

LIVEKIT_URL=wss://your-livekit-server

LIVEKIT_API_KEY=...

LIVEKIT_API_SECRET=...

Frontend (apps/frontend/.env.local):

NEXT_PUBLIC_API_URL=http://localhost:4000

NEXT_PUBLIC_GOOGLE_CLIENT_ID=...

15Deployment

Build all packages for production:

bash

# Build everything
pnpm build

# The frontend outputs to apps/frontend/.next (standalone mode)
# The backend compiles to apps/backend/dist/

The frontend is configured with output: 'standalone' for containerized deployments. The backend runs via tsx watch in development and compiles to JavaScript for production.

For the Electron desktop app, see the desktop/ directory. It wraps the frontend in an Electron shell.

Questions? Open an issue on GitHub.