Discovery Module

Location: apps/api/src/modules/discovery/

Aggregate roots: ConnectionIntent

The Discovery context implements "Make Connections" (CON-01..03). Users declare a ConnectionIntent and are matched against compatible candidates based on shared interest count, intent compatibility, and optional geo/interest filters.

---

Intent Types

Intent	Compatible With
networking	networking
friends	friends
romantic	romantic
mentor	mentee
mentee	mentor
collab	collab

---

Prisma Model

connection_intents

Field	Type	Notes
userId	UUID PK FK	One per user
intent	String	See intent types above
note	String?	Card text (shown in discovery feed)
isActive	Boolean	false = hidden from candidates
updatedAt	DateTime
createdAt	DateTime

---

Key Methods

Method	Description
upsertIntent(userId, dto)	Set/update intent
getIntent(userId)	Get current intent
getCandidates(userId, filters)	Ranked candidates by shared interest count
getMentors(userId, filters)	Mentors with expertise gap ≥ minExpertiseGap
getPeopleDirectory(userId, opts)	Browseable user directory with isFollowing field

Candidate Ranking

getCandidates algorithm:

1. Exclude: self, banned users, opted-out users (isActive=false).
2. Filter by intentCompatibility(viewerIntent).
3. Optional geo filter: city and/or country.
4. Optional interest filter: interestSlug (must share that specific interest).
5. Count shared interests via user_interests join.
6. Sort: shared interest count DESC, then createdAt ASC.
7. Paginate with cursor (userId-based).

Mentor Matching

getMentors finds users who:

1. Have ConnectionIntent.intent = 'mentor' and isActive = true.
2. Share at least one interest with the viewer.
3. Mentor's UserInterest.expertise exceeds viewer's by minExpertiseGap (default 2, clamped 1..4).
4. Optional: filter by a specific interestSlug.

---

HTTP Endpoints

All under /api/v1/discovery/. Require JwtAuthGuard.

Method	Path	Description
PUT	/discovery/intent	Upsert my intent { intent, note?, isActive? }
GET	/discovery/intent	Get my intent
GET	/discovery/candidates	Ranked discovery candidates
GET	/discovery/mentors	Mentor matches ?interestSlug&minExpertiseGap
GET	/discovery/people	People directory ?q&cursor&limit

Query Parameters for /discovery/candidates

Param	Type	Notes
intent	String?	Override stored intent for query
interestSlug	String?	Filter by shared interest
country	String?	Geo filter
city	String?	Geo filter
minShared	Int?	Min shared interests (default 1)
limit	Int?	Page size (default 20, max 50)
cursor	String?	userId cursor for pagination

---

People Directory

GET /discovery/people returns paginated users with:

• id, username, firstName, lastName, profilePicUrl
• isFollowing: boolean — whether the viewer follows this user
• sharedInterests: number — count of shared interests

Used by the mobile "People" tab and contact picker.