Monorepo Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The SoulSeer project is structured as a TypeScript-based monorepo that manages the frontend, backend, and shared logic within a single repository. This architecture enables a unified development workflow, type safety across the network boundary, and simplified dependency management for the spiritual consultation platform.
Sources: package.json:1-6, README.md:27-33
Workspace Structure
The project utilizes npm workspaces to manage three distinct packages. This allows the team to run commands across all sub-projects or target specific ones while maintaining a single node_modules at the root for common dependencies.
| Workspace | Path | Primary Technology | Purpose |
|---|---|---|---|
| Shared | /shared | TypeScript, Zod, Drizzle | Common types, Drizzle schemas, and validation logic. |
| Client | /client | React (Vite), TypeScript | The user-facing web application. |
| Server | /server | Node.js, Express, TypeScript | The REST API and WebSocket backend. |
Sources: package.json:4-8, README.md:34-55
Dependency Flow and Integration
The architecture is designed so that both the client and server depend on the shared package. This ensures that data models and validation logic are identical on both ends of the API.
The diagram above illustrates how the shared package acts as the foundation for the other two workspaces, ensuring consistency.
Sources: server/package.json:28, README.md:27-33
Shared Package: The Source of Truth
The @soulseer/shared package contains the core business logic definitions. It exports Drizzle ORM schemas, TypeScript types, and Zod validators. By importing @soulseer/shared/validators in both the Express server and the React client, the project enforces strict input validation before requests are even sent and after they are received.
Key Shared Components
- Validators: Zod schemas for pagination, user roles, and reading sessions.
- Enums: Centralized definitions for statuses like
readingStatusSchema(pending,accepted,completed). - Data Models: TypeScript interfaces inferred from Zod schemas for use in frontend forms and backend controllers.
Sources: shared/package.json:1-35, shared/src/validators.ts:1-25
Server Workspace
The server is a TypeScript Express application responsible for business logic, database orchestration, and real-time services. It mounts various route handlers and integrates with external services for payments and real-time communication.
Server Lifecycle and Services
The server entry point initializes critical services before listening for connections.
Core Middleware Stack
The server implements several layers of security and processing:
- Helmet: Security headers including a strict Content Security Policy.
- CORS: Configured via environment variables to allow specific frontend origins.
- Pino: Structured HTTP logging.
- Rate Limiting: General, strict (for auth), and webhook-specific limiters.
- JSON Parsing: 2MB limit for standard requests, bypassed for Stripe webhooks.
Sources: server/src/index.ts:25-85, server/package.json:1-20
Client Workspace
The client is a Single Page Application (SPA) built with React and Vite. It consumes the @soulseer/shared package for type safety during API calls and form validation.
Build and Deployment Configuration
The monorepo supports multiple deployment strategies through configuration files located at the root and within sub-packages:
- Netlify: Configured via
netlify.tomlto build the client and proxy API requests to functions. - Vercel: Configured via
vercel.jsonfor SPA rewrites and serverless function handling. - Production Bundle: In production environments, the server can serve the client's static
distfolder directly as a fallback.
Sources: netlify.toml:1-15, vercel.json:1-15, server/src/production.ts:50-65
Cross-Package Scripts
The root package.json provides unified scripts to manage the entire monorepo, using the -w (workspace) flag to direct commands.
| Script | Command | Description |
|---|---|---|
npm run dev | concurrently ... | Starts both client and server development servers. |
npm run build | npm run build -w shared && ... | Builds the project in the correct dependency order. |
npm run db:migrate | drizzle-kit migrate | Executes database migrations via the server workspace. |
npm run typecheck | tsc -p ... --noEmit | Validates TypeScript across all three workspaces. |
Sources: package.json:7-22, README.md:65-75
Summary
The SoulSeer Monorepo Architecture provides a robust environment for full-stack TypeScript development. By centralizing the schema and validation logic in a shared workspace, the project minimizes runtime errors and ensures that the client and server remain in sync as the spiritual community platform evolves. The use of standard workspace patterns allows the project to scale across different cloud providers like Fly.io, Vercel, or Netlify with minimal reconfiguration.
Sources: README.md:27-33, server/src/production.ts:1-10