A real-time messaging backend built with Express, TypeScript, Prisma, PostgreSQL, Redis, and Socket.IO. It powers private conversations, group chats, media attachments, unread message tracking, and live real-time messaging for the PeriChat application.
https://perichat-livid.vercel.app
Frontend Repository: https://github.com/KhalidHayKay/PeriChat
- Handles user authentication with token-based sessions
- Supports private one-to-one conversations
- Supports group conversations and membership actions
- Stores and delivers messages in real time over Socket.IO
- Tracks unread counts per conversation
- Supports file and media attachments in messages
- Runs in Docker with PostgreSQL and Redis for local development and deployment
- Node.js 22
- Express 5 + TypeScript
- Prisma ORM
- PostgreSQL
- Redis
- Socket.IO
- Docker Compose
src/
app.ts
server.ts
config/
controllers/
dtos/
errors/
lib/
middlewares/
routes/
services/
types/
validator/
prisma/
schema.prisma
compose.yaml
compose.override.yaml
Dockerfile
start.sh
git clone https://github.com/KhalidHayKay/PeriChat-Express.git
cd PeriChat-Expresscp .env.example .envUpdate the values in .env for your local or deployment environment. The repository includes a ready-to-use example with defaults for local Docker development.
The base compose.yaml is intentionally simple and production-friendly. For local development, the repository already includes compose.override.yaml, which mounts the source code into the container so the app can be developed with hot reload support.
If you need to recreate it, the relevant content is:
services:
app:
volumes:
- ./:/var/www/docker compose up --build -dThis starts:
app— the Express APIdb— PostgreSQLredis— Redis
docker compose exec app yarn prisma generate
docker compose exec app yarn prisma migrate deploy- API base URL: http://localhost:8050
- Health check: http://localhost:8050/health
If you want to run the app directly on your machine:
yarn install
yarn prisma generate
yarn devThe development script uses tsx watch, so changes to the source are picked up automatically.
The app uses the values from .env. The most important ones are:
APP_ENV=local
APP_PORT=8050
APP_URL=http://localhost:8050
DB_HOST=db
DB_PORT=5432
DB_DATABASE=perichat
DB_USERNAME=perichat-postgres
DB_PASSWORD=admin
DATABASE_URL=postgresql://perichat-postgres:admin@db:5432/perichat?schema=public
REDIS_URL=redis://redis:6379
CORS_ORIGINS=http://localhost:5173All API routes are mounted under /api.
POST /api/auth/login
POST /api/auth/register
POST /api/auth/logout
GET /api/conversations
GET /api/conversations/suggestions
GET /api/conversations/:id
GET /api/conversations/:id/older
POST /api/messaging
POST /api/messaging/first
POST /api/group
GET /api/group/candidates
POST /api/group/:id/join
POST /api/group/:id/leave
The backend exposes Socket.IO for live messaging. Clients connect with a token in the handshake and can join conversation rooms to receive updates.
Key events include:
message:sent— broadcast when a message is createdcreated:conversation— emitted when a first message creates a new conversationcreated:group— emitted when a group is createdusers:online,user:online,user:offline— presence updates
The Docker setup is defined in compose.yaml and compose.override.yaml:
appruns the Express server on the port defined byAPP_PORTdbruns PostgreSQL with a named volume for persistenceredisruns Redis with a named volume for persistence- Local development uses the override file to mount the working directory into the container
- The app uses Prisma for database access and schema management.
- The server also exposes
/healthfor simple uptime checks. - The default local development environment is configured for Docker-based development, but you can also run the API directly with Yarn.