Database Setup

Overview

The Money monorepo uses MongoDB as its primary database for the Secure and CashGap applications. This guide covers setting up MongoDB for development and production environments.

Database Requirements

MongoDB Version

MongoDB 4.4 or higher

Connection Method

MongoDB URI connection string

ORM/ODM

Mongoose for schema and queries

Authentication

Username/password authentication

Applications Using MongoDB

Secure App

Stores:

User accounts and profiles
Authentication sessions
Password vault entries
Encryption keys and metadata
OAuth account links
Email verification tokens

CashGap App

Stores:

User accounts and profiles
Transaction records
Financial data
Authentication sessions
User preferences

The Secure app stores sensitive encrypted data. Ensure your database has appropriate security measures, backups, and access controls.

Development Setup

Option 1: Local MongoDB

Install MongoDB

Choose your installation method:

brew tap mongodb/brew
brew install mongodb-community
brew services start mongodb-community

Verify installation

Check that MongoDB is running:

# Connect to MongoDB
mongosh

# Or check the process
ps aux | grep mongod

Configure connection string

Add to your .env file:

MONGODB_URI=mongodb://localhost:27017/money-dev

For separate databases per app:

# In apps/secure/.env
MONGODB_URI=mongodb://localhost:27017/secure-dev

# In apps/cashgap/.env
MONGODB_URI=mongodb://localhost:27017/cashgap-dev

Test connection

Start your app and verify database connectivity:

pnpm dev --filter=secure

Check logs for successful database connection.

Option 2: MongoDB Atlas (Cloud)

Recommended for teams and production-like development environments.

Create MongoDB Atlas account

Create a cluster

Click “Build a Database”
Choose “Shared” (free tier)
Select your cloud provider and region
Name your cluster
Click “Create Cluster”

Configure database access

Go to “Database Access”
Click “Add New Database User”
Create username and strong password
Grant “Read and write to any database” permission
Click “Add User”

Configure network access

Go to “Network Access”
Click “Add IP Address”
For development: Click “Allow Access from Anywhere” (0.0.0.0/0)
For production: Add specific IP addresses
Click “Confirm”

Get connection string

Click “Connect” on your cluster
Choose “Connect your application”
Copy the connection string
Replace <password> with your database password
Replace <database> with your database name (e.g., money-dev)

Add to environment variables

MONGODB_URI=mongodb+srv://username:[email protected]/money-dev?retryWrites=true&w=majority

Production Setup

MongoDB Atlas (Recommended)

Create production cluster

Create a separate cluster for production:

Use a dedicated cluster (M10+) for better performance
Choose a region close to your deployment
Enable backups (automatic on paid tiers)
Consider multi-region deployment for high availability

Security configuration

Database users: Create dedicated user for production with minimal required permissions
Network access: Whitelist only your production server IPs
Encryption: Enable encryption at rest (available on paid tiers)
TLS/SSL: Always enabled by default on Atlas

Performance optimization

Indexes: Create indexes on frequently queried fields
Connection pooling: Configure appropriate pool size
Read preference: Use appropriate read preference for your use case
Monitoring: Enable MongoDB Atlas monitoring and alerts

Backup strategy

Enable continuous backups (available on M10+)
Configure backup retention policy
Test restore procedures
Consider point-in-time recovery

Configure connection string

Add to production environment variables:

MONGODB_URI=mongodb+srv://prod-user:[email protected]/money-prod?retryWrites=true&w=majority&maxPoolSize=10

Self-Hosted MongoDB

For self-hosted deployments:

Install MongoDB on server

Follow MongoDB installation guides for your OS/platform

Enable authentication

# Create admin user
mongosh
use admin
db.createUser({
  user: "admin",
  pwd: "strong-password",
  roles: [{ role: "userAdminAnyDatabase", db: "admin" }]
})

Enable authentication in mongod.conf:

security:
  authorization: enabled

Configure firewall

# Allow MongoDB port only from app servers
sudo ufw allow from <app-server-ip> to any port 27017

Enable TLS/SSL

Configure TLS in mongod.conf:

net:
  tls:
    mode: requireTLS
    certificateKeyFile: /path/to/mongodb.pem

Setup replication (recommended)

Configure a replica set for high availability:

mongosh
rs.initiate({
  _id: "rs0",
  members: [
    { _id: 0, host: "mongo1:27017" },
    { _id: 1, host: "mongo2:27017" },
    { _id: 2, host: "mongo3:27017" }
  ]
})

Database Schema

The applications use Mongoose for schema definition and queries:

Connection Management

Connections are managed per-app:

// apps/secure/src/lib/db/connection.ts
import mongoose from 'mongoose';

const MONGODB_URI = process.env.MONGODB_URI;

if (!MONGODB_URI) {
  throw new Error('Please define MONGODB_URI environment variable');
}

export async function connectToDatabase() {
  if (mongoose.connection.readyState >= 1) {
    return;
  }

  return mongoose.connect(MONGODB_URI);
}

Mongoose Models

Models are defined in each app’s models directory:

User models
Session models
App-specific data models

Database Operations

Clearing Development Database

A utility script is available to clear development databases:

# Clear all development data
pnpm tsx scripts/clear-databases.ts

This script is for development only and will delete all data. Never run in production!

Database Migrations

Currently, the project does not use formal migrations. Schema changes are handled by:

Updating Mongoose models
Deploying code changes
Running manual migration scripts if needed

Consider adding a migration tool like:

Seeding Data

For development, you can seed test data:

// Example seed script
import { connectToDatabase } from './lib/db';
import { User } from './models/User';

async function seed() {
  await connectToDatabase();
  
  await User.create({
    email: '[email protected]',
    name: 'Test User',
    // ... other fields
  });
  
  console.log('Seed completed');
}

seed();

Performance Optimization

Indexing

Create indexes on frequently queried fields:

// In Mongoose model
const UserSchema = new Schema({
  email: { type: String, required: true, unique: true, index: true },
  createdAt: { type: Date, default: Date.now, index: true }
});

Connection Pooling

Configure connection pool size in URI:

MONGODB_URI=mongodb+srv://...?maxPoolSize=10&minPoolSize=5

Query Optimization

Use lean() for read-only queries
Select only needed fields
Use pagination for large result sets
Avoid N+1 queries with populate()

Monitoring

MongoDB Atlas Monitoring

Atlas provides built-in monitoring:

Real-time metrics
Query performance insights
Index recommendations
Alerts for issues

Application-Level Monitoring

Log database operations:

mongoose.set('debug', process.env.NODE_ENV === 'development');

Backup and Recovery

MongoDB Atlas Backups

Continuous backups on M10+ clusters
Point-in-time recovery
Automated snapshots
Download backup archives

Manual Backup

# Export database
mongodump --uri="mongodb://localhost:27017/money-dev" --out=./backup

# Restore database
mongorestore --uri="mongodb://localhost:27017/money-dev" ./backup

Backup Strategy Recommendations

Automated daily backups
Retain backups for 30 days minimum
Test restore procedures monthly
Store backups in separate location
Encrypt backup files

Troubleshooting

Connection Refused

# Check if MongoDB is running
sudo systemctl status mongod

# Check logs
sudo journalctl -u mongod

# Verify port is open
sudo netstat -tlnp | grep 27017

Authentication Failed

Verify username and password are correct
Check user has permissions on target database
Ensure authentication is enabled in MongoDB config
Verify connection string format

Slow Queries

Enable query profiling:
```
db.setProfilingLevel(2)
```
Check for missing indexes
Use explain() to analyze queries
Review MongoDB Atlas Performance Advisor

Connection Pool Exhausted

Increase maxPoolSize in connection string
Check for connection leaks in code
Ensure connections are properly closed
Monitor connection usage

Security Best Practices

Always follow these security practices for production databases:

Enable authentication: Never run without authentication
Use strong passwords: Generate random passwords
Restrict network access: Whitelist specific IPs only
Enable TLS/SSL: Encrypt data in transit
Encrypt at rest: Enable encryption for stored data
Regular updates: Keep MongoDB updated
Audit logs: Enable and monitor audit logs
Least privilege: Grant minimum required permissions
Separate environments: Use different databases for dev/staging/prod
Regular backups: Maintain backup schedule

Next Steps

Environment Variables

Configure database connection strings

Deployment Overview

Deploy with database configuration

Running Locally

Start development with database

Setup Guide

Complete development setup

Development Guide

Deployment

Contributing

​Overview

​Database Requirements

MongoDB Version

Connection Method

ORM/ODM

Authentication

​Applications Using MongoDB

​Secure App

​CashGap App

​Development Setup

​Option 1: Local MongoDB

​Option 2: MongoDB Atlas (Cloud)

​Production Setup

​MongoDB Atlas (Recommended)

​Self-Hosted MongoDB

​Database Schema

​Connection Management

​Mongoose Models

​Database Operations

​Clearing Development Database

​Database Migrations

​Seeding Data

​Performance Optimization

​Indexing

​Connection Pooling

​Query Optimization

​Monitoring

​MongoDB Atlas Monitoring

​Application-Level Monitoring

​Backup and Recovery

​MongoDB Atlas Backups

​Manual Backup

​Backup Strategy Recommendations

​Troubleshooting

​Connection Refused

​Authentication Failed

​Slow Queries

​Connection Pool Exhausted

​Security Best Practices

​Next Steps

Environment Variables

Deployment Overview

Running Locally

Setup Guide

Build docs developers (and LLMs) love

Overview

Database Requirements

Applications Using MongoDB

Secure App

CashGap App

Development Setup

Option 1: Local MongoDB

Option 2: MongoDB Atlas (Cloud)

Production Setup

MongoDB Atlas (Recommended)

Self-Hosted MongoDB

Database Schema

Connection Management

Mongoose Models

Database Operations

Clearing Development Database

Database Migrations

Seeding Data

Performance Optimization

Indexing

Connection Pooling

Query Optimization

Monitoring

MongoDB Atlas Monitoring

Application-Level Monitoring

Backup and Recovery

MongoDB Atlas Backups

Manual Backup

Backup Strategy Recommendations

Troubleshooting

Connection Refused

Authentication Failed

Slow Queries

Connection Pool Exhausted

Security Best Practices

Next Steps