Building a real-time chat application from scratch to deeply understand distributed systems architecture, using Effect-ts
Phases may be re-arranged or new ones introduced as the project evolves.
Learn distributed systems by building a Discord-like chat app that scales from 1 to 10,000+ concurrent users using Effect.
Learning focus:
- Distributed systems patterns (consensus, sharding, pub/sub)
- Effect in a complex real-world domain
- Documenting architectural decisions
Not focused on:
- Production readiness or feature completeness
- Perfect code from day one (learning by making mistakes)
Start Simple. Add Complexity When Needed.
- Phases 1-11: Single server, core features
- Phase 14: Load testing to find bottlenecks
- Phases 15+: Add distributed patterns as needed
Avoid premature optimization to learn why distributed patterns exist, not just how to use them.
Current:
- Bun + Effect-ts
- PostgreSQL
git clone https://github.com/RATIU5/flowline
cd flowline
pnpm install
pnpm devPrerequisites: Bun v1.3.5+, PostgreSQL 17+
- WebSocket connection
- User authentication (with DB)
- Database persistence (in progress)
- Direct messages for 1:1 communication
- Channels & spaces for 1:N communication
- User presence (active, offline, away, custom)
- Custom UI/UX library
- Typing indicators
- Message types (text, markdown, forward, reply, quote)
- Reactions to messages
- Threads (group similar messages in a sub-container)
- File uploads
- Public API to work for different client and load testing
- Load testing (10k users)
- Redis pub/sub
- Message queue
For contributors:
- Documentation Process - How to document decisions
- Decision Log - Architecture choices & trade-offs
- Phase Retrospectives - Lessons learned
Why build this publicly?
Learning distributed systems for career growth. Documenting decisions shows growth over time and provides interview material.
"The best way to learn distributed systems is to build one, break it, and fix it."
Last Updated: April 10, 2026