Reader Discovery & Profiles
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Reader Discovery & Profiles system is the core navigational and informational hub of the SoulSeer platform. It enables clients to browse, filter, and view detailed profiles of spiritual readers. The system is designed to provide real-time information regarding reader availability (online/offline status), specialties, pricing for various reading types (Chat, Voice, Video), and community-driven feedback through reviews and ratings.
Sources: README.md:5-10, client/src/pages/readers/ReadersPage.tsx:135-145
Reader Discovery Architecture
The discovery process is primarily handled through the ReadersPage and the HomePage. The platform utilizes a specialized hook, useReaders, to poll the backend for the latest reader data, ensuring that availability statuses are kept current.
Filtering and Sorting Logic
The discovery interface provides several filtering mechanisms to help clients find suitable readers. Filtering occurs on the client side based on data fetched from the GET /api/readers endpoint.
| Filter Category | Implementation | Description |
|---|---|---|
| Specialty | String matching on specialties field | Filters readers by specific gifts (e.g., Tarot, Medium, Astrology). |
| Reading Type | Pricing check (pricingChat, pricingVoice, pricingVideo) | Filters readers based on whether they offer a specific communication medium. |
| Status | Boolean check on isOnline | Filters by current availability. |
| Sort Order | list.sort((a, b) => ...) | Prioritizes online readers at the top of the list. |
Sources: client/src/pages/readers/ReadersPage.tsx:148-175, server/src/routes/users.ts:13-33
Discovery Data Flow
The following diagram illustrates how reader data flows from the database to the user interface.
The system uses a polling interval of 30,000ms to refresh the reader list on the frontend.
Sources: client/src/pages/HomePage.tsx:75, client/src/pages/readers/ReadersPage.tsx:136, server/src/routes/users.ts:13-25
Reader Profiles
Individual reader profiles are accessed via the ReaderProfilePage. This page aggregates public profile information with historical performance data, such as average ratings and client reviews.
Profile Components and Data Points
The ReaderPublic interface defines the data structure used for these profiles. Key fields include:
- Identity:
fullName,username, andprofileImage. - Expertise:
bioand a comma-separated list ofspecialties. - Pricing: Distinct rates for
pricingChat,pricingVoice, andpricingVideo(stored in cents). - Social Proof:
avgRating(rounded to one decimal) andreviewCount.
Sources: client/src/types/index.ts:31-45, server/src/routes/users.ts:114-118
Reader Profile Sequence
When a user views a profile, the system fetches both the reader's basic info and their associated reviews in a single request.
API Endpoints for Discovery
The following endpoints in server/src/routes/users.ts facilitate discovery:
| Method | Endpoint | Description |
|---|---|---|
GET | /api/readers | Returns all reader profiles not marked as deleted, ordered by online status. |
GET | /api/readers/online | Returns only readers where isOnline is true. |
GET | /api/readers/:id | Returns a full profile including average rating, review count, and a list of the 20 most recent reviews. |
Sources: server/src/routes/users.ts:13, server/src/routes/users.ts:37, server/src/routes/users.ts:55-110
Validation and Data Constraints
To ensure data integrity, the system employs Zod schemas for filtering and profile updates.
- Reader Filtering: The
readerFilterSchemavalidates query parameters such aspage,limit,specialty,type, andonlinestatus. - Pricing Constraints: Rates are validated as non-negative integers representing cents, with a maximum limit of 100,000 ($1,000.00).
- Profile Metadata:
biois limited to 2,000 characters, andspecialtiesare validated as an array of strings (max 20 tags).
Sources: shared/src/validators.ts:133-140, shared/src/validators.ts:38-42, shared/src/validators.ts:110-120
Conclusion
The Reader Discovery & Profiles system provides a robust interface for matching clients with spiritual practitioners. By combining real-time status tracking via polling, flexible client-side filtering, and detailed profile views enriched with ratings and reviews, the system ensures a transparent and efficient discovery experience.
Sources: client/src/pages/readers/ReadersPage.tsx:180-205, server/src/routes/users.ts:125-135