Hybrid Architecture Design

Relevant source files

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

• README_START_HERE.md
• DELIVERY_SUMMARY.md
• RBAC_SYSTEM_ARCHITECTURE.md
• COMPLETE_APP_README.md
• PROJECT_COMPLETION_SUMMARY.md
• docs/RBAC_ARCHITECTURE.md
• docs/MONGODB_INTEGRATION.md

Introduction

The BankChase project utilizes a Hybrid Database Architecture designed to balance strict data consistency with horizontal scalability and flexibility. This design leverages PostgreSQL (via Supabase) for core banking operations requiring ACID compliance and structured relationships, alongside MongoDB (via Atlas) for high-volume, flexible data such as notifications, analytics, and transaction history logs.

This architecture ensures that sensitive authentication and Role-Based Access Control (RBAC) data remain in a highly secure, structured environment, while non-critical but voluminous data can scale independently.

Sources: README_START_HERE.md:46-49, DELIVERY_SUMMARY.md:1-10

---

Core Database Separation Strategy

The system partitions data based on its operational requirements. Structured data governed by strict security policies (RLS) resides in PostgreSQL, while flexible or ephemeral data resides in MongoDB.

Data Partitioning Logic

Data Category	Database Provider	Primary Reason
RBAC & Identity	PostgreSQL	Requires strict relational integrity and Row-Level Security (RLS).
Financial Accounts	PostgreSQL	Demands ACID compliance for balance integrity.
Audit Logs (Admin)	PostgreSQL	Ensures immutable, structured trails for compliance.
Notifications	MongoDB	High volume, flexible schema, and benefits from TTL cleanup.
Transaction History	MongoDB	Scalable storage for high-frequency ledger logs.
User Preferences	MongoDB	Schema-less flexibility for UI/UX settings.
Device Tracking	MongoDB	Frequent updates and TTL-based session management.

Sources: DELIVERY_SUMMARY.md:33-43, README_START_HERE.md:100-103

---

Architectural Components and Flow

The hybrid design is orchestrated through a central API layer that routes requests to the appropriate data provider. The following diagram illustrates the request flow and data separation.

---

PostgreSQL Implementation: Security and Integrity

PostgreSQL acts as the "Source of Truth" for identity and financial status. It implements an 8-layer security architecture, including database-level Row-Level Security (RLS) to ensure data isolation.

Key Schemas and Policies

• Users & RBAC: Manages roles (Customer, Admin, Auditor) and hashed credentials using Bcrypt.
• Zero-Balance Guarantee: New accounts are initialized at $0.00, protected by RLS to prevent unauthorized initial balances.
• Audit Trail: Admin actions are logged to immutable PostgreSQL tables including IP addresses and user agents.

Sources: README_START_HERE.md:52-59, DELIVERY_SUMMARY.md:12-25, COMPLETE_APP_README.md:40-65

---

MongoDB Implementation: Flexibility and Scale

MongoDB is utilized for data that is unstructured or high-velocity. It uses TTL (Time-To-Live) indexes for automatic data cleanup of old notifications or session devices.

Collection Strategy

• Collections: includes notifications, preferences, transactions, analytics, and devices.
• Connection Management: Implements connection pooling specifically optimized for Vercel Serverless Functions to prevent database socket exhaustion.

MongoDB Schema Summary

// Example: Notification Document structure in MongoDB
{
  "userId": "UUID",
  "type": "alert|promo|security",
  "title": "String",
  "message": "String",
  "read": "Boolean",
  "expiresAt": "ISODate" // TTL Index field
}

Sources: DELIVERY_SUMMARY.md:38-43, docs/MONGODB_INTEGRATION.md:100-150

---

Integration and Operations

The hybrid approach requires a unified integration layer found in the lib/ directory.

Key Integration Files

• lib/mongodb/client.ts: Manages the singleton connection to Atlas.
• lib/mongodb/operations.ts: Standardized CRUD operations for NoSQL data.
• lib/rbac.ts: Permission helpers that enforce access across both data sources.

Transactional Sequence Diagram

This diagram shows how a transaction is processed across the hybrid stack.

---

Performance and Cost Metrics

The hybrid architecture is optimized for cost-efficiency at scale, particularly for the target of 1 million users.

Metric	PostgreSQL Performance	MongoDB Performance
Login/Auth	50ms	N/A
Transaction Record	10ms (ACID)	5ms (Log)
Notification Fetch	N/A	15ms
Throughput	10K/sec	100K/sec

Sources: DELIVERY_SUMMARY.md:158-185, README_START_HERE.md:275-285

Conclusion

The BankChase Hybrid Architecture Design provides a robust framework for modern fintech applications. By utilizing PostgreSQL for security and integrity while offloading high-volume operations to MongoDB, the system achieves a highly competitive cost-per-user ratio ($0.0045/month) without sacrificing the "Zero-Balance Guarantee" or strict audit compliance required for banking platforms.

Sources: DELIVERY_SUMMARY.md:170-175, README_START_HERE.md:280-282