Quick Start & Setup Guide
Relevant source files
The following files were used as context for generating this wiki page:
The Quick Start & Setup Guide provides a streamlined path for developers and administrators to deploy, configure, and initialize the BankChase platform. This guide covers the hybrid database architecture, including MongoDB Atlas for flexible data and PostgreSQL (Supabase/Neon) for core relational integrity, as well as the Role-Based Access Control (RBAC) security framework.
BankChase is built on Next.js 16 and utilizes an 8-layer security architecture to ensure strict data isolation and immutable audit trails. The scope of this guide includes environment configuration, database initialization, and local development setup.
Sources: README_START_HERE.md:1-20, DOCUMENTATION_INDEX.md:3-10, DELIVERY_SUMMARY.md:1-15
Core Architecture & Database Setup
BankChase utilizes a hybrid database strategy to optimize for performance, scale, and compliance. Relational data such as user roles, accounts, and audit logs are stored in PostgreSQL (managed via Supabase or Neon), while flexible, high-volume data like notifications and analytics reside in MongoDB.
Hybrid Data Flow
The following diagram illustrates how requests are routed between the frontend and the hybrid database backend.
Database Initialization
Initialization requires setting up connection strings for both MongoDB and PostgreSQL providers.
- PostgreSQL (Neon/Supabase): Initialize core tables (users, accounts, audit_logs) by running provided migration scripts or API triggers.
- MongoDB Atlas: Create a free cluster and obtain the connection string for
.env.local.
Sources: NEON_QUICK_GUIDE.md:20-40, MONGODB_QUICK_START.md:10-25, README_START_HERE.md:112-117
Authentication & RBAC Initialization
The BankChase security model relies on a three-role system: Customer, Admin, and Auditor. The setup requires a specific flow to ensure Two-Factor Authentication (2FA) is active for all sessions.
User Onboarding Flow
Key Security Parameters
| Parameter | Type | Default/Requirement | Description |
|---|---|---|---|
JWT_SECRET | String | Base64 32-char | Used for HS256 token signing |
2FA Code | Numeric | 6 Digits | Expires in 5 minutes; single-use |
Session Duration | Time | 7 Days | Configurable JWT expiration |
Bcrypt Rounds | Integer | 10 | Cost factor for password hashing |
Sources: README_START_HERE.md:162-175, DELIVERY_SUMMARY.md:16-25
Development Environment Setup
Developers can choose between a local Docker-based setup or a standard Node.js development environment.
Local Development Options
Option 1: Node.js standard
# Install dependencies
npm install
# Start development server
npm run dev
Option 2: Docker Compose
# Start all services (Postgres, Redis, FastAPI backend)
docker-compose up -d
Sources: SETUP_COMPLETE.md:103-125, DOCUMENTATION_INDEX.md:130-145
Essential Environment Variables
A .env.local file must be created in the root directory with the following mandatory keys:
# MongoDB
MONGODB_URI=mongodb+srv://...
# Supabase / Neon
NEXT_PUBLIC_SUPABASE_URL=https://...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
DATABASE_URL=postgresql://...
# Authentication
JWT_SECRET=<generate_secret>
NEXT_PUBLIC_SITE_URL=http://localhost:3000
Sources: README_START_HERE.md:235-250, DEPLOYMENT_CHECKLIST.md:24-35
Deployment & Verification
Before moving to production, the system status must be verified using internal health check endpoints.
Pre-Deployment Checklist
- Configure Supabase/Neon Redirect URLs with wildcard patterns (
**). - Run
003-rbac-and-auth.sqlmigration in the SQL Editor. - Set
NEXT_PUBLIC_SITE_URLfor production environment. - Verify MongoDB IP whitelisting for deployment targets (e.g., Vercel IPs).
Sources: DEPLOYMENT_CHECKLIST.md:5-20, REDIRECT_URLS_SETUP_SUMMARY.md:20-35, SYSTEM_STATUS_REPORT.md:200-215
Verification Endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/api/health/mongodb | GET | Verifies Atlas cluster connectivity |
/api/admin/init-db | POST | Triggers PostgreSQL table creation |
/api/admin/audit-logs | GET | Confirms RBAC admin access |
Sources: README_START_HERE.md:120-125, SYSTEM_STATUS_REPORT.md:158-165, NEON_QUICK_GUIDE.md:45-50
Summary
The Quick Start & Setup Guide ensures that the BankChase application is correctly configured with its hybrid database and security layers. By following the initialization of MongoDB and PostgreSQL, configuring essential environment variables, and verifying the RBAC flow via 2FA, developers can successfully transition from local development to a production-ready deployment. All configuration relies on strict data isolation and zero-balance guarantees for new accounts to maintain banking compliance.
Sources: README_START_HERE.md:295-305, DELIVERY_SUMMARY.md:310-325