PRD Example 19: Real-time Chat Application

Difficulty: Advanced | Project Type: Full Stack Web App | Time: 2-3 weeks

---

Overview

What	A real-time chat application with rooms and direct messages
Who	Teams or communities who need simple, self-hosted chat
Why	Provides real-time communication without relying on third-party services

---

Core Features (MVP)

1. User Registration: Sign up with username and password
2. Chat Rooms: Create and join public chat rooms
3. Real-time Messages: Send/receive messages instantly via WebSocket
4. Message History: Load previous messages when joining room
5. Online Status: See who's currently online in a room

---

Non-Goals

Will NOT build:

• Direct messages (rooms only)
• File/image sharing
• Message editing or deletion
• Message reactions or threads
• Voice or video chat
• Push notifications
• Admin moderation tools
• Message search
• End-to-end encryption

Will NOT use:

• Third-party auth providers (OAuth, etc.)
• External chat services
• Redis for pub/sub (use in-memory)
• Complex ORM (use simple queries)

---

Technical Constraints

Frontend	Next.js 14, TypeScript, Tailwind CSS
Backend	Next.js API Routes
Real-time	Socket.io
Database	SQLite with Prisma
Auth	NextAuth.js with credentials
Testing	Jest, Playwright for E2E
Deploy	Self-hosted (Docker)

---

Success Criteria

• [ ] Users can register and log in
• [ ] Users can create chat rooms
• [ ] Messages appear instantly for all room members
• [ ] Message history loads on room join
• [ ] Online users list updates in real-time
• [ ] Works with 50 concurrent users
• [ ] All tests pass

---

Implementation Phases

Phase 1: Project Setup & Auth

Goal: Set up project with authentication

Tasks:

1. Create Next.js project with TypeScript
2. Set up Prisma with SQLite
3. Create User model (id, username, passwordHash)
4. Implement NextAuth with credentials provider
5. Create login/register pages

Verification:

npm run dev
# App runs on http://localhost:3000

# Register new user → Success
# Login → Redirects to home
# Access protected route → Works when logged in

Deliverables: Project with working auth

---

Phase 2: Room Management

Goal: Create and list chat rooms

Tasks:

1. Create Room model (id, name, createdBy)
2. Create RoomMember model (userId, roomId, joinedAt)
3. Build room list page
4. Build create room form
5. Build room detail page (placeholder for messages)

Verification:

1. Create room "General"
2. Room appears in list
3. Click room → Opens room page
4. Other users can see and join room

Deliverables: Room CRUD functionality

---

Phase 3: Real-time Messaging

Goal: Implement WebSocket chat

Tasks:

1. Set up Socket.io server
2. Create Message model (id, content, userId, roomId, createdAt)
3. Implement send message (emit to room)
4. Implement receive message (update UI)
5. Load message history on room join

Verification:

1. User A sends message in Room 1
2. User B sees message instantly
3. User C joins Room 1 → sees message history
4. Messages persist after page refresh

Deliverables: Real-time chat working

---

Phase 4: Online Status & Polish

Goal: Show online users and polish UX

Tasks:

1. Track connected users per room
2. Broadcast join/leave events
3. Display online users list
4. Add typing indicator
5. Add timestamps and user avatars

Verification:

1. Join room → Online count increases
2. Leave room → Online count decreases
3. See "UserX is typing..." indicator
4. Messages show timestamp and username

Deliverables: Online presence features

---

Phase 5: Testing & Deployment

Goal: Test and deploy

Tasks:

1. Write Jest unit tests for API routes
2. Write Playwright E2E tests for chat flow
3. Create Dockerfile
4. Create docker-compose.yml
5. Document deployment steps

Verification:

npm test
# All tests pass

docker-compose up
# App runs in container

# Load test with 50 concurrent connections
# Messages still instant

Deliverables: Deployed, tested application

---

Database Schema

model User {
  id           String   @id @default(uuid())
  username     String   @unique
  passwordHash String
  createdAt    DateTime @default(now())
  messages     Message[]
  rooms        RoomMember[]
}

model Room {
  id        String   @id @default(uuid())
  name      String
  createdAt DateTime @default(now())
  members   RoomMember[]
  messages  Message[]
}

model RoomMember {
  userId   String
  roomId   String
  joinedAt DateTime @default(now())
  user     User     @relation(fields: [userId], references: [id])
  room     Room     @relation(fields: [roomId], references: [id])
  @@id([userId, roomId])
}

model Message {
  id        String   @id @default(uuid())
  content   String
  userId    String
  roomId    String
  createdAt DateTime @default(now())
  user      User     @relation(fields: [userId], references: [id])
  room      Room     @relation(fields: [roomId], references: [id])
}

---

Agent Rules

Always	Ask First	Never
Hash passwords before storing	Before changing database schema	Store plain text passwords
Validate message content length	Before adding new features	Send messages without auth
Escape HTML in messages (XSS)	Before changing Socket.io events	Expose user passwords
Handle WebSocket disconnects		Delete message history