External API Services
Relevant source files
The following files were used as context for generating this wiki page:
SoulSeer integrates several third-party platforms to provide authentication, payment processing, real-time communication, and media management. These services form the backbone of the platform's commercial and interactive features.
Sources: README.md:16-24, client/src/pages/PrivacyPolicyPage.tsx:77-83
Architecture Overview
The backend is configured as an Express server that acts as an intermediary between the client and various external APIs. Security headers via Helmet and CORS configurations are specifically tuned to allow communication with these external domains, particularly for real-time video/voice and payment frames.
The architecture uses a monorepo structure where the server handles business logic and service orchestration while the client interfaces directly with specific provider SDKs for high-bandwidth tasks like video streaming.
Sources: server/src/index.ts:35-50, README.md:26-52
Core Service Integrations
Stripe: Payments and Payouts
Stripe is utilized for both inbound customer payments and outbound reader payouts (via Stripe Connect). The system supports a "Prepay Balance" model where clients top up their accounts before engaging in readings.
- Payment Intents: Created to handle top-ups (minimum $5.00).
- Webhooks: Used to asynchronously update user balances upon successful payment verification.
- Stripe Connect: Express accounts are provisioned for readers to facilitate 70/30 revenue splits and payouts.
| Feature | Endpoint / Usage | Description |
|---|---|---|
| Top-up | POST /api/payments/create-intent | Generates a Stripe Client Secret for the frontend. |
| Webhook | POST /api/webhooks/stripe | Processes payment_intent.succeeded events. |
| Payouts | POST /api/admin/payouts/:readerId | Triggers transfer from platform to reader Connect account. |
| Onboarding | stripe.accountLinks.create | Generates URLs for reader identity verification. |
Sources: server/src/routes/payments.ts:16-100, server/src/routes/admin.ts:148-185, README.md:79-84
Auth0: Identity and Access Management
Auth0 serves as the primary authentication provider. The system uses Auth0 JWTs for securing API routes and the Auth0 Management API for administrative tasks such as provisioning new reader accounts.
Agora: Real-Time Communication
Agora provides the infrastructure for live chat, voice, and video sessions. The platform uses Agora RTC (Real-Time Communication) for media streams and RTM (Real-Time Messaging) for text chat.
- Security: The server generates temporary Agora tokens to authorize clients to join specific channels.
- Privacy: Voice and video streams are transmitted in real-time and are not recorded by the SoulSeer servers.
Sources: README.md:10-23, client/src/pages/PrivacyPolicyPage.tsx:59-65, server/package.json:28
Cloudinary: Media Storage
Cloudinary is used for hosting and transforming user-uploaded images, primarily reader profile photos.
- Implementation: The server uses
multerto handle in-memory file buffers before uploading them to Cloudinary. - Configuration: Requires
CLOUDINARY_URLor specific cloud credentials. Access is restricted to images under 5MB in JPEG, PNG, or WebP formats.
Sources: server/src/routes/admin.ts:187-235, client/src/pages/PrivacyPolicyPage.tsx:77-83
Configuration and Security
External services are managed via environment variables and restricted through Content Security Policy (CSP) directives in the main server entry point.
| Service | CSP Directive | Purpose |
|---|---|---|
| Agora | connect-src: *.agora.io | WebSocket/API connections for media. |
| Stripe | frame-src: *.stripe.com | Embedding Stripe Elements for secure data entry. |
| Fonts | font-src: fonts.gstatic.com | Loading Google Fonts. |
Sources: server/src/index.ts:35-54, server/package.json:26-45
Conclusion
The External API Services module effectively offloads complex tasks like PCI-compliant payment handling, secure authentication, and global scale real-time media delivery to specialized providers. This allows the SoulSeer platform to maintain a lightweight core while providing robust, enterprise-grade features for its spiritual community.