Local Setup & Development
Relevant source files
The following files were used as context for generating this wiki page:
SoulSeer is built as a monorepo consisting of a React frontend, a Node.js Express backend, and a shared TypeScript package for types and validation logic. The development environment is designed to run both the client and server concurrently using npm workspaces to manage dependencies across the project.
Sources: README.md:21-47, package.json:3-9
Project Architecture
The application follows a structured monorepo pattern where code is shared between the frontend and backend to ensure type safety.
- Client: A React application powered by Vite, located in
client/. - Server: An Express API server located in
server/. - Shared: Common TypeScript schemas and validators located in
shared/.
System Component Flow
The following diagram illustrates the relationship between the local development environment components:
The flow shows how the shared package provides the foundation for both client and server, which then interact with various third-party services.
Sources: README.md:21-47, package.json:3-9, server/src/config.ts:60-100
Environment Prerequisites
Before beginning local setup, several external accounts and tools are required as specified in the project configuration.
| Requirement | Version / Type | Purpose |
|---|---|---|
| Node.js | 18+ | Runtime environment |
| npm | 9+ | Package manager |
| Database | Neon (PostgreSQL) | Primary data storage |
| Auth | Auth0 | User authentication and JWT |
| Payments | Stripe | Credit system and reader payouts |
| Real-Time | Agora | Voice, Video, and Chat (RTC/RTM) |
Sources: README.md:52-57, package.json:44-58
Installation and Configuration
The setup process involves cloning the repository, installing dependencies across all workspaces, and configuring environment variables.
Initial Commands
# Clone the repository
git clone https://github.com/EmilynnJ/soulseer.git
cd soulseer
# Install dependencies for all workspaces
npm install
# Configure environment
cp .env.example .env
Sources: README.md:62-72
Environment Variables
The server validates environment variables using Zod. The following keys are required for the application to start:
| Variable | Description | Default (Local) |
|---|---|---|
DATABASE_URL | Neon/Postgres connection string | Required |
PORT | Backend server port | 5000 |
CORS_ORIGIN | Allowed frontend origin | http://localhost:3000 |
AUTH0_DOMAIN | Auth0 tenant domain | Required |
AUTH0_AUDIENCE | API Identifier for JWT verification | Required |
AGORA_APP_ID | Agora project application ID | Required |
STRIPE_SECRET_KEY | Stripe private API key | Required |
Sources: server/src/config.ts:60-85
Development Workflow
The project uses concurrently to manage multiple processes during development.
Running the Application
Running npm run dev from the root directory executes the following sequence:
- Starts the Vite dev server for the client on port
3000. - Starts the Express server using
tsx watchon port5000.
Database Management
Database operations are handled via Drizzle ORM. Developers can use the following scripts from the root:
npm run db:generate: Generates migrations from the schema.npm run db:migrate: Applies migrations to the Neon database.npm run db:push: Pushes schema changes directly (use with caution).npm run db:studio: Opens a GUI to browse the local/remote database.
Sources: package.json:23-26, server/package.json:10-12
Build and Deployment Logic
Local builds can be tested to simulate the production environment.
Local Build Commands
# Build all packages in order: shared -> server -> client
npm run build
Sources: package.json:15-16
Deployment Configuration
The project includes a netlify.toml for frontend hosting and a server/src/production.ts for Fly.io backend deployment.
- Netlify: Proxies
/api/*requests to serverless functions and handles SPA routing by falling back toindex.html. - Fly.io: Serves the API and static files from
client/distusing a single Express instance.
Sources: netlify.toml:8-25, server/src/production.ts:47-68
Summary
Setting up SoulSeer locally requires a Node.js 18+ environment and several third-party service credentials (Auth0, Stripe, Agora, Neon). The development workflow leverages npm workspaces and concurrently to sync the React frontend and Express backend, while Drizzle ORM manages the PostgreSQL schema transitions. Proper configuration of the .env file is critical, as the backend performs strict validation of required service keys upon startup.