Deployment Infrastructure
Relevant source files
The following files were used as context for generating this wiki page:
The SoulSeer platform utilizes a hybrid deployment strategy designed for high availability, security, and scalability. The infrastructure is primarily built around two hosting providers: Fly.io for the core Express API and real-time services, and Netlify for the frontend Single Page Application (SPA) and serverless function proxies.
The system architecture supports environment-specific configurations (development, production, and test) and integrates with third-party services including Neon (PostgreSQL), Auth0 (Authentication), Stripe (Payments), and Agora (Real-time Communications).
Sources: fly.toml:1-12, netlify.toml:1-10, server/src/config.ts:60-75
Fly.io Application Infrastructure
The core backend application is deployed to Fly.io as a containerized Node.js service. This infrastructure manages the API server and, in certain production configurations, serves static client files as an integrated SPA.
Virtual Machine Configuration
The Fly.io deployment is configured to run in the ord (Chicago) region with specific resource allocations to ensure cost-efficiency and performance.
| Parameter | Value | Description |
|---|---|---|
| Memory | 1GB (1024MB) | Standard memory allocation for the Node.js process. |
| CPU Kind | Shared | Efficient shared CPU resources. |
| CPUs | 1 | Single core execution. |
| Internal Port | 8080 | The port where the Express server listens within the container. |
Sources: fly.toml:7-21, server/src/production.ts:70-75
Production Server Logic
In the production environment on Fly.io, the server executes server/src/production.ts. This entry point differs from the standard index by specifically handling SPA routing and static asset delivery from client/dist.
The diagram shows the request flow through the Fly.io infrastructure, where the Express server acts as both an API provider and a static file server for the React frontend.
Sources: server/src/production.ts:10-68, fly.toml:13-17
Netlify Frontend Infrastructure
Netlify provides the primary hosting for the frontend application. It is configured to handle build processes, security headers, and redirection logic for SPA routing.
Build and Environment
The Netlify build pipeline compiles the React application and prepares serverless functions.
- Node Version: 20
- Publish Directory:
client/dist - Functions Directory:
netlify/functions - Build Command:
npm run build
Sources: netlify.toml:4-14
Redirection and Proxying
To maintain a unified origin for the frontend, Netlify is configured to proxy API requests to the serverless function layer or the main API server.
| Rule Type | From | To | Status |
|---|---|---|---|
| API Proxy | /api/* | /.netlify/functions/api/:splat | 200 |
| SPA Fallback | /* | /index.html | 200 |
Sources: netlify.toml:19-29
Environment Configuration and Security
The infrastructure relies on a centralized configuration management system using Zod for validation. This ensures all necessary secrets and endpoints are present before the deployment starts.
Security Headers
Both the server-side code (via helmet) and the Netlify configuration enforce strict security policies to protect user data.
The diagram illustrates the defense-in-depth approach used across the deployment infrastructure.
Sources: server/src/index.ts:32-55, netlify.toml:32-39
Service Integration Configuration
The server/src/config.ts file acts as the bridge between infrastructure environment variables and application logic. It dynamically resolves database connection strings from multiple potential providers (Neon, Vercel, or standard DATABASE_URL).
| Service | Config Mapping | Metadata |
|---|---|---|
| Database | DATABASE_URL | Supports Neon and Vercel aliases. |
| Auth0 | AUTH0_DOMAIN | Validates domain and audience strings. |
| Stripe | STRIPE_SECRET_KEY | Managed via environment secrets. |
| Agora | AGORA_APP_ID | Required for RTC/RTM functionality. |
Sources: server/src/config.ts:40-60, package.json:35-50
Graceful Shutdown and Health Checks
The Fly.io infrastructure is designed to handle lifecycle events via the standard SIGTERM and SIGINT signals. When a shutdown is initiated, the server follows a specific sequence to prevent data loss or orphaned connections.
- Stop Services: The
billingServiceandwsService(WebSocket) are shut down first. - Close Server: The HTTP server stops accepting new connections.
- End Pool: The database connection pool is drained and closed.
- Exit: The process exits after a maximum 10-second timeout.
Health checks are exposed at /api/health and /api/db-check to allow Fly.io and Netlify to monitor the operational status of the instance.
Sources: server/src/index.ts:133-165, server/src/production.ts:42-50
Summary
The SoulSeer deployment infrastructure is a robust multi-cloud setup. By leveraging Fly.io's global regions for low-latency backend services and Netlify's optimized CDN for frontend delivery, the project achieves a high degree of technical resilience. The configuration-driven approach allows for seamless transitions between development and production environments while maintaining strict security standards through automated header injection and environment variable validation.