Flately helps users find compatible roommates through guided onboarding, weighted preference matching, and real-time messaging.
The success of Flately is attributed to a highly coordinated and specialized team:
- Mitul Bhatia: Team Lead — Coordinated the entire project lifecycle and managed cross-module integrations.
- Hardik Maheshwari: Deployment & User Flow Lead — Spearheaded the deployment architecture and orchestrated the complete user journey.
- Ajeesh Amreet: Recommendation & Chat Engineer — Architected the core matching engine and implemented the live Socket.IO-based chat features.
- Akshat Chauhan: Database Lead — Designed the Entity-Relationship models and managed the MongoDB Atlas integration.
- Suryansh Singh: Strategic Lead, UI & Documentation Manager — Designed the minimalist UI, managed all structural diagrams, authored the core architectural reports, and guided strategic direction.
Flately solves a practical housing pain point: roommate decisions are high-risk and usually made with low-quality context.
Our app improves this by combining:
- Structured user and lifestyle profiling
- Preference-weighted match scoring
- Mutual-interest conversion into direct chat
flowchart LR
Landing[Landing] --> Start[Questionnaire]
Start --> Auth{Auth Choice}
Auth --> Signup[Signup]
Auth --> Login[Login]
Auth --> Google[Google OAuth]
Signup --> Onboarding[Onboarding]
Login --> App[App Home]
Google --> Callback[Callback]
Callback --> App
Onboarding --> App
App --> Discover[Discover]
Discover --> Matches[Matches]
Matches --> Chat[Chat]
App --> Profile[Profile]
Route mapping:
- Landing:
/ - Questionnaire:
/start - Signup:
/signup - Login:
/login - Callback:
/auth/callback - Onboarding:
/app/onboarding - App Home:
/app - Discover:
/app/discover - Matches:
/app/matches - Chat:
/app/chat/:matchId? - Profile:
/app/profile
%%{init: {'theme':'base','themeVariables': {
'primaryColor':'#EDF7F6',
'primaryTextColor':'#0F4C5C',
'primaryBorderColor':'#0F4C5C',
'lineColor':'#0F4C5C',
'secondaryColor':'#F7F5EF',
'tertiaryColor':'#FFFFFF'
}}}%%
flowchart LR
subgraph FE[Frontend Layer]
UI[React 19 + Vite 7]
Store[Redux Toolkit]
Guards[Auth Bootstrap + Route Guards]
SocketClient[Socket.IO Client]
UI --> Store --> Guards --> SocketClient
end
subgraph BE[Backend Layer]
API[Express 5 API]
JWT[JWT Middleware Chain]
Domain[Domain Modules\nAuth, Profiles, Preferences, Discovery, Matches, Chat, Uploads]
Realtime[Socket.IO Gateway]
API --> JWT --> Domain
Realtime --> Domain
end
subgraph DATA[Data + Services]
DB[(MongoDB Atlas via Prisma)]
OAuth[Google OAuth]
Media[Cloudinary Signed Uploads]
end
FE -->|REST + Bearer JWT| API
FE -->|WebSocket| Realtime
Domain --> DB
Domain --> OAuth
Domain --> Media
| Technology | Version |
|---|---|
| React | 19.2.3 |
| Vite | 7.2.4 |
| TypeScript | 5.9.3 |
| Redux Toolkit | 2.11.2 |
| React Router DOM | 6.30.3 |
| Socket.IO Client | 4.8.3 |
| TailwindCSS | 4.1.18 |
| Framer Motion | 12.29.2 |
| React Hook Form | 7.71.1 |
| Zod | 4.3.5 |
| Playwright | 1.59.1 |
| Technology | Version |
|---|---|
| Express | 5.2.1 |
| TypeScript | 5.9.3 |
| Prisma + Prisma Client | 6.19.2 |
| Socket.IO | 4.8.3 |
| jsonwebtoken | 9.0.3 |
| Zod | 3.23.8 |
| Helmet | 8.1.0 |
| express-rate-limit | 8.2.1 |
| tsx | 4.19.2 |
| Vitest | 2.1.8 |
All UML diagrams are verified against the actual TypeScript codebase. Each diagram has a Mermaid source (.mmd) and a rendered PNG.
📋 Full Documentation: UML_DIAGRAMS.md | 🗺️ Planning: Future Plan
| # | Diagram | What It Shows | Source | Image |
|---|---|---|---|---|
| 1 | Class Diagram | 18 core classes, Strategy/Factory/Template Method patterns | .mmd | .png |
| 2 | Use Case Diagram | 5 actors, 15 use cases across 7 system modules | .mmd | .png |
| 3 | ERD | 7 Prisma/MongoDB models with all FK/PK constraints | .mmd | .png |
| 4 | Activity Diagram | Full user journey: login → discovery → match → chat | .mmd | .png |
| 5 | Sequence Diagram | Swipe → onboarding check → mutual match creation | .mmd | .png |
Shows all TypeScript classes, interfaces, abstract classes, and their relationships.
Key Patterns: Strategy, Factory, Template Method, Adapter, Singleton, Observer
Maps external actors to 15 system operations across 7 modules.
Actors: Guest User, Authenticated User, Google OAuth, Cloudinary CDN, Socket.IO Client
All 7 Prisma models with field types, primary keys, foreign keys, and cardinalities.
Models: User, Profile, Preference, Swipe, Match, Conversation, Message
End-to-end state flow from login through onboarding, discovery, matching, and real-time chat.
Key Flows: Authentication gates, onboarding checks, mutual match detection
Complete POST /discovery/swipe interaction flow through all backend layers.
Participants: Frontend → Controller → Service → Matching → Matches → MongoDB
-
Authentication
- Email/password signup and login
- Backend-managed Google OAuth
- JWT-protected app access
-
Onboarding + Profile Intelligence
- Structured profile capture
- Preference capture with weighted dimensions
- Onboarding gate enforcement before discovery and matching
-
Discovery and Matching
- Candidate feed retrieval
- Swipe actions with mutual-like match creation logic
-
Real-time Chat
- Match-scoped conversations
- Socket.IO-based message delivery
- Conversation and message persistence
-
Engineering Quality
- Manual fetch transport with Adapter + Strategy architecture
- Typed full-stack contracts and validation layers
- Architecture and verification docs for reproducible delivery
- Node.js >= 18
- npm >= 9
- MongoDB Atlas (or local Mongo)
- Google OAuth credentials
- Cloudinary credentials
cd backend
npm install
npx prisma generate
npm run devBackend: http://localhost:4000
cd frontend
npm install
npm run devFrontend: http://localhost:5174
curl http://localhost:4000/healthExpected response:
{ "status": "ok" }All verification complete as of 2026-05-03:
- ✅ Backend typecheck: pass
- ✅ Backend tests: pass
- ✅ Backend build: pass
- ✅ Frontend typecheck: pass
- ✅ Frontend tests: pass
- ✅ Frontend build: pass
- ✅ Manual auth flows: verified
Testing Guide: Manual Auth End-to-End Verification
📖 Complete Documentation Index - Master navigation for all documentation
| Category | Documents |
|---|---|
| Getting Started | Setup · User Flow · Architecture |
| Implementation | Backend Reference · Frontend Guide · API Reference |
| Database | Schema · Matching Algorithm |
| Testing | Auth Verification |
| Design | UML Diagrams · System Design Study Guide |
| Planning | Future Plan · Historical Archive |
- Open Product Summary to frame the problem.
- Use Hero User Journey to explain conversion flow.
- Present Architecture Diagram for technical depth.
- Show Diagram Library to prove system rigor.
- Close with Verification Snapshot for execution credibility.
Brand colors used in this README:
- #0F4C5C
- #0A3742
- #EDF7F6
- #F7F5EF