Polyglot Database Strategy

Relevant source files

The following files were used as context for generating this wiki page:

• MONGODB_QUICK_START.md
• HYBRID_ARCHITECTURE_SUMMARY.md
• DELIVERY_SUMMARY.md
• README_START_HERE.md
• docs/RBAC_ARCHITECTURE.md
• lib/mongodb/client.ts
• lib/db.ts

BankChase utilizes a hybrid architecture that combines the strengths of relational and non-relational databases. This polyglot strategy leverages PostgreSQL (via Supabase or Neon) for structured, ACID-compliant data and MongoDB (via Atlas) for high-volume, flexible document storage. This approach is designed to optimize performance, scalability, and maintainability across different banking features.

Sources: HYBRID_ARCHITECTURE_SUMMARY.md:3-8, DELIVERY_SUMMARY.md:28-34

Architecture Overview

The system divides data responsibilities between two primary engines. PostgreSQL serves as the single source of truth for identity and core account structures, while MongoDB handles volatile or high-volume data such as notifications and transaction logs.

Database Separation Strategy

PostgreSQL (Relational Layer)

PostgreSQL is utilized for data requiring strict referential integrity, complex joins, and ACID compliance. It is the primary engine for Role-Based Access Control (RBAC) and core banking structures.

• Primary Tables: users, accounts, two_factor_codes, password_resets, admin_audit_logs.
• Security Features: Row-Level Security (RLS) and foreign key constraints.
• Capacity: Safely handles ~500GB (Supabase tiering).

Sources: HYBRID_ARCHITECTURE_SUMMARY.md:44-58, DELIVERY_SUMMARY.md:46-55

MongoDB (Document Layer)

MongoDB is employed for high-volume data with flexible schemas and data that benefits from automatic lifecycle management via Time-To-Live (TTL) indexes.

• Primary Collections: notifications, preferences, transactions, analytics, devices, auditLogs.
• Scaling: Horizontal scaling through Atlas auto-scaling.
• Cleanup: TTL indexes facilitate automatic removal of old notifications and logs.

Sources: HYBRID_ARCHITECTURE_SUMMARY.md:60-76, MONGODB_QUICK_START.md:120-130

Data Allocation and Features

The following table summarizes which project features are assigned to each database engine:

Data Type	Engine	Feature/Purpose	Growth Pattern
Authentication	PostgreSQL	Registration, Login, 2FA	Linear
RBAC	PostgreSQL	User Roles & Permissions	Linear
Accounts	PostgreSQL	Zero-balance account definitions	Linear
Notifications	MongoDB	User alerts & system notifications	Rapid (TTL Managed)
Transactions	MongoDB	Transaction history & records	Unlimited
Analytics	MongoDB	Monthly summaries	Linear
Audit Trails	Both	PostgreSQL (Admin actions), MongoDB (App trail)	Rapid

Sources: HYBRID_ARCHITECTURE_SUMMARY.md:49-75, DELIVERY_SUMMARY.md:72-88

Implementation and Integration

Connection Management

The application implements client-level connection pooling for both engines to support Vercel Functions.

// lib/mongodb/client.ts
// MongoDB uses a client-level pool (min: 2, max: 10)
import { MongoClient } from 'mongodb';

// lib/db.ts
// PostgreSQL (Neon) uses an HTTP-based serverless driver
import { neon } from '@neondatabase/serverless';

Sources: HYBRID_ARCHITECTURE_SUMMARY.md:107-122, lib/mongodb/client.ts, lib/db.ts

Synchronization Strategy

The project follows a One-way Sync Strategy (PostgreSQL → MongoDB). When core identity or account data changes in PostgreSQL, it is optionally denormalized into MongoDB for performance, but the system never writes to PostgreSQL from MongoDB to avoid bidirectional synchronization complexities.

Performance Metrics

The polyglot approach allows the system to achieve high throughput by offloading high-frequency writes and flexible reads to MongoDB.

Operation	PostgreSQL Performance	MongoDB Performance	Total Capacity
Login	50ms	N/A	10K/sec
Transaction Recording	5ms	5ms	50K/sec
Notification Retrieval	N/A	15ms	100K/sec
Audit Log Query	100ms	N/A	5K/sec

Sources: HYBRID_ARCHITECTURE_SUMMARY.md:200-222, DELIVERY_SUMMARY.md:118-132

Summary

The Polyglot Database Strategy in BankChase ensures that sensitive identity and financial structures remain protected by PostgreSQL's ACID properties and Row-Level Security, while high-volume features like notifications and transaction history scale horizontally using MongoDB. This hybrid model provides a cost-effective (~$0.0045/user/month for 1M users) and high-performance foundation for secure banking operations.

Sources: HYBRID_ARCHITECTURE_SUMMARY.md:88-103, DELIVERY_SUMMARY.md:136-146