Echoline

Real-time chat — direct messages, groups, read receipts, presence, and media.

Features

• Direct messages and group chats
• Real-time message delivery over WebSockets (Socket.IO)
• Read receipts — "Seen" and "Read by N"
• Typing indicators
• Online/offline presence
• Image sharing via presigned Cloudflare R2 uploads — media never touches the API
• Blocking with automatic DM cleanup
• Soft-delete your own messages
• Dark mode (system default, d hotkey toggle)
• Optimistic UI — messages appear instantly and sync in the background

Quick Start

Prerequisites: Bun >= 1.4 and Docker.

# 1. Install dependencies
bun install

# 2. Start PostgreSQL
docker compose up -d

# 3. Create apps/api/.env and apps/web/.env (see Environment below)

# 4. Push the database schema
bun run --cwd apps/api db:push

# 5. Start the dev servers (web on :3000, api on :3001)
bun run dev

Open http://localhost:3000 and sign up.

Environment

apps/api/.env

Variable	Purpose
DATABASE_URL	postgresql://myapp:devpassword@localhost:5432/myapp
BETTER_AUTH_SECRET	Better Auth session secret
BETTER_AUTH_URL	http://localhost:3001
CLIENT_URL	CORS origin + Socket.IO CORS (http://localhost:3000)
PORT	API port (default 3001)
R2_ACCOUNT_ID	Cloudflare R2 account id
R2_ACCESS_KEY_ID	R2 access key
R2_SECRET_ACCESS_KEY	R2 secret key
R2_BUCKET	R2 bucket name

apps/web/.env

Variable	Purpose
NEXT_PUBLIC_API_URL	API base URL (http://localhost:3001)

Tech Stack

Layer	Tech
Frontend	Next.js 16 (App Router), React 19, Tailwind CSS v4, shadcn/ui (Base UI), TanStack Query v5
Backend	Hono on Bun, Socket.IO (@socket.io/bun-engine), Better Auth, Zod
Data	PostgreSQL 18, Drizzle ORM (schema applied via drizzle-kit push)
Media	Cloudflare R2 — presigned PUT/GET URLs
Tooling	Bun workspaces, Turborepo, ESLint 9, Prettier 3

Project Structure

apps/api     # Hono + Socket.IO backend — REST, auth, realtime, R2 signing
apps/web     # Next.js 16 chat client
packages/    # shared ESLint & TypeScript config scaffolds (not yet adopted)
docs/        # deep-dive documentation

See docs/ARCHITECTURE.md for endpoints, realtime events, data flow, and the database schema.

License

MIT © 2026 Echoline contributors