Introduction to SoulSeer
Relevant source files
The following files were used as context for generating this wiki page:
SoulSeer is a premium spiritual consultation platform designed to connect gifted psychic readers with clients seeking guidance through a mystical and professional interface. The platform facilitates real-time interactions via live chat, voice, and video sessions, supported by a robust prepay balance system and a community-driven ecosystem.
The system is architected as a monorepo containing a React-based frontend, a Node.js/Express backend, and a shared library for type definitions and validation logic. It emphasizes ethical standards, ensuring readers retain a majority (70%) of their earnings while providing clients with a secure, judgment-free environment for spiritual growth.
Sources: README.md:3-8, README.md:68-71, client/src/pages/AboutPage.tsx:13-17
Architecture Overview
SoulSeer utilizes a modern tech stack centered around real-time communication and secure financial transactions.
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | React (Vite) + TypeScript | Responsive, mystical UI and session management |
| Backend | Node.js + Express + TypeScript | API handling, business logic, and billing |
| Database | Neon (PostgreSQL) + Drizzle ORM | Persistent storage for users, sessions, and transactions |
| Real-Time | Agora (RTC + RTM) | Low-latency voice, video, and chat streaming |
| Auth | Auth0 | Secure JWT-based authentication |
| Payments | Stripe + Stripe Connect | Fund management and reader payouts |
Sources: README.md:14-23, server/src/index.ts:141-143
System Data Flow
The following diagram illustrates how a client interacts with the platform to initiate and fund a session.
Key Features
1. Pay-Per-Minute Readings
The core functionality of SoulSeer is the per-minute billing system for live sessions. Clients add funds to a prepay balance (minimum $5.00) which is then deducted in real-time as a session progresses.
Sources: README.md:39-44, client/src/pages/HelpPage.tsx:49-59, client/src/pages/reading/ReadingSessionPage.tsx:640-645
2. Multi-Modal Consultations
SoulSeer supports three distinct reading types, each with independent rates set by the reader:
- Chat: Text-based communication using Agora RTM.
- Voice: Audio-only calls using Agora RTC.
- Video: Face-to-face sessions using Agora RTC.
Sources: client/src/pages/HelpPage.tsx:54-58, shared/src/validators.ts:16, client/src/pages/reading/ReadingSessionPage.tsx:498-540
3. Reader Ecosystem
Readers are vetted through an application process and manage their own profiles, including bios, specialties (e.g., Tarot, Astrology), and availability toggles.
Sources: client/src/pages/HelpPage.tsx:180-210, README.md:10-12, shared/src/validators.ts:109-119
Core Modules and API Structure
API Routing Table
The backend exposes several critical endpoints for managing the platform lifecycle. All protected routes require an Auth0 JWT.
| Method | Route | Purpose |
|---|---|---|
POST | /api/auth/sync | Syncs Auth0 user data with the local database |
GET | /api/readers | Retrieves public reader profiles |
POST | /api/readings/on-demand | Initiates a new reading request |
POST | /api/readings/:id/end | Finalizes a session and calculates costs |
POST | /api/payments/create-intent | Initiates a Stripe payment for balance top-up |
GET | /api/forum/posts | Fetches community discussions |
Sources: README.md:48-60, server/src/index.ts:101-131
Reading Session Logic
When a session starts, the server generates Agora tokens and the client establishes a connection. A heartbeat mechanism ensures the session remains active, and a billing service monitors the client's balance.
Security and Privacy
SoulSeer implements several layers of security to protect user data and financial integrity:
- Rate Limiting: General, strict (auth), and webhook-specific limiters are applied to prevent abuse.
- Helmet Headers: Standard security headers including Content Security Policy (CSP) tailored for Agora and Stripe integration.
- Data Confidentiality: Reading content (voice/video) is transmitted in real-time and not recorded. Chat transcripts are stored for user reference but are private between participants.
- PCI Compliance: Payment data is handled exclusively by Stripe; SoulSeer only retains transaction metadata.
Sources: server/src/index.ts:33-58, client/src/pages/PrivacyPolicyPage.tsx:50-55, client/src/pages/PrivacyPolicyPage.tsx:28-32
Summary
SoulSeer is a specialized platform that bridges the gap between spiritual guidance and modern technology. By integrating real-time media via Agora, secure payments via Stripe, and a community-focused forum, it provides a comprehensive toolset for both spiritual seekers and professional readers. The project's monorepo structure and TypeScript-first approach ensure a maintainable and scalable codebase.
Sources: README.md:3-12, README.md:25-36