Financial Services Application - Architecture Documentation

1. Executive Summary

This document outlines the architecture for our trading and disbursement platform designed to manage client investments from onboarding through trading and disbursement. The architecture follows a multi-tiered approach with clear separation of concerns to ensure scalability, security, and maintainability.

2. System Overview

The platform follows a modern microservices architecture with the following key components:

React-based frontend applications
Material UI for consistent design
Next.js for server-side rendering and API routes
REST API Gateway for secure service communication
MongoDB for data storage
Blob storage for document management
Separation of data and document storage
OAuth 2.0 for authentication and authorization

3. Architecture Components

3.1 Architecture Diagram

High-Level System Architecture

The overall architecture showing key components and their relationships in the financial services application.

3.2 Component Descriptions

3.2.1 Database Layer

Technology Stack: MongoDB

Key Collections:

contacts - Contact profile information
deals - Investment program details
capitals - Investment capital details
trades - Trading transaction records
disbursements - Disbursement transaction records

3.2.2 Business Logic Layer

Technology Stack: Next.js

Key Services:

Client Management Service (/pages/api/steps/*): Manages client onboarding workflow and data
Deal Management Engine (/pages/api/deals/*): Core transactional engine for investment deals
Trading Engine (part of /pages/api/deals/*): Implements trading workflow and execution
Disbursement Processor (/pages/api/disbursement/*): Manages fund distribution
Document Management Service (/pages/api/documents/*): Handles document storage via Vercel Blob Storage

Implementation Patterns:

The application follows several key implementation patterns:

API Route Pattern: Business logic is implemented in Next.js API routes, organized by domain
Server-side Database Access: MongoDB integration through Next.js server components with connection pooling
Configuration-Driven Workflow: Steps and forms are dynamically rendered based on configuration
Document-Based Data Model: Flexible schema using MongoDB's document model
Role-Based Authorization: Permissions system for securing access to functionality

3.2.3 Data Flow Patterns

Client Request → API Route → Business Logic → Database → Response
Document Upload → API Route → Storage Service → Blob Storage → Metadata in Database → Response
Workflow Progression → API Route → State Validation → State Update → Event Recording → Response
Authentication Flow → Client → OAuth 2.0 → Token Validation → Protected Resource Access → Response

3.2.4 API Layer

Technology Stack: REST API with OpenAPI specification

Authentication: OAuth 2.0 with JWT tokens

Key Endpoints:

/api/clients - Client management
/api/assessment - Risk assessment
/api/trades - Trading operations
/api/disbursements - Disbursement management

3.2.5 User Interface

Technology Stack: React with Material UI

Key Features:

Responsive design for multiple devices
Dashboard for client portfolio overview
Trading interface with real-time updates
Reporting and analytics visualization

4. Data Flow

4.1 Client Onboarding Process

Client Onboarding Workflow

The process flow for new client registration and account setup, showing interactions between system components.

sequenceDiagram participant Client as Client participant UI as User Interface participant API as API Gateway participant CMS as Client Management participant KYC as KYC Service participant DB as Database Note over Client,DB: New Client Registration Process Client->>+UI: Submit registration form UI->>+API: POST /api/clients API->>+CMS: Process client registration rect rgb(240, 249, 255) Note right of CMS: Validation Phase CMS->>CMS: Validate client data CMS-->>API: Request additional info (if needed) API-->>UI: Display data requirements UI-->>Client: Request missing information Client->>UI: Provide additional data UI->>API: Submit complete data API->>CMS: Process complete data end CMS->>+KYC: Initiate KYC check KYC->>KYC: Perform identity verification KYC->>KYC: Check compliance requirements KYC-->>-CMS: Return KYC status alt KYC Approved CMS->>+DB: Store client profile DB-->>-CMS: Confirm storage CMS-->>-API: Return client profile with ID API-->>-UI: Display welcome & next steps UI-->>Client: Show account dashboard else KYC Pending CMS-->>API: Return pending status API-->>UI: Display verification pending UI-->>Client: Show pending status page else KYC Rejected CMS-->>API: Return rejection reason API-->>UI: Display rejection message UI-->>Client: Show contact support options end

4.2 Trading Process

Trading Process Flow

The sequence of operations for processing trade requests, from client submission through execution and settlement.

sequenceDiagram participant Client as Client participant UI as Trading Interface participant API as API Gateway participant Auth as Auth Service participant TE as Trading Engine participant Assess as Risk Assessment participant Broker as External Broker participant DB as Database Note over Client,DB: End-to-End Trading Flow Client->>+UI: Submit trade request UI->>+API: POST /api/trades API->>+Auth: Validate session & permissions Auth-->>-API: Authorization response alt Authorized API->>+TE: Forward trade request rect rgb(236, 253, 245) Note right of TE: Pre-Trade Validation TE->>+Assess: Risk assessment request Assess->>Assess: Evaluate client portfolio Assess->>Assess: Check trade parameters Assess->>Assess: Verify regulatory compliance Assess-->>-TE: Risk assessment result alt Risk Assessment Passed TE->>TE: Validate trade parameters TE->>TE: Apply trading rules TE->>TE: Determine execution strategy else Risk Assessment Failed TE-->>API: Return risk assessment failure API-->>UI: Display validation error UI-->>Client: Show rejection reason end end rect rgb(254, 242, 242) Note right of TE: Trade Execution TE->>+Broker: Submit trade for execution Broker->>Broker: Process trade Broker-->>-TE: Trade execution confirmation end rect rgb(237, 233, 254) Note right of TE: Post-Trade Processing TE->>+DB: Store trade details DB-->>-TE: Confirm storage TE-->>-API: Return trade confirmation API-->>-UI: Display trade receipt UI-->>Client: Show trade confirmation TE->>DB: Update portfolio position TE->>Client: Send trade notification end else Unauthorized API-->>UI: Return authorization error UI-->>Client: Display access denied message end

5. Security Architecture

5.1 Security Layers

Security Framework Architecture

The multi-layered security approach implemented throughout the system to protect data and operations.

5.2 Authentication Flow

OAuth 2.0 Authentication Process

The secure authentication flow using OAuth 2.0 with JWT tokens for API access.

sequenceDiagram participant Client as Client participant App as Application participant Auth as Auth Server participant API as API Services participant Resource as Protected Resources Note over Client,Resource: OAuth 2.0 Authorization Code Flow with PKCE %% Initial Authentication Client->>+App: Access application App->>App: Generate code_verifier App->>App: Create code_challenge App->>+Auth: Authorization request with code_challenge Auth->>Client: Redirect to login page Client->>Auth: Provide credentials alt Valid Credentials Auth->>Auth: Validate credentials Auth->>Auth: Generate authorization code Auth-->>-App: Return authorization code App->>+Auth: Token request with code & code_verifier Auth->>Auth: Verify code & code_verifier Auth->>Auth: Generate JWT tokens Auth-->>-App: Return access & refresh tokens App->>App: Store tokens securely loop Resource Access App->>+API: API request with access token API->>API: Validate token signature API->>API: Check token expiration API->>API: Verify permissions alt Token Valid API->>+Resource: Forward validated request Resource-->>-API: Return requested data API-->>-App: Return API response App-->>Client: Display data else Token Invalid/Expired API-->>App: Return 401 Unauthorized App->>+Auth: Request token refresh Auth->>Auth: Validate refresh token Auth-->>-App: Issue new access token App->>API: Retry request with new token end end else Invalid Credentials Auth-->>App: Authentication failed App-->>Client: Display login error end

6. Deployment Architecture

6.1 Infrastructure Diagram

Cloud Infrastructure Architecture

The cloud infrastructure architecture showing how the application is deployed and managed on Vercel.

6.2 Deployment Platform

The trading platform is deployed on Vercel, which serves as our primary deployment layer. Vercel leverages AWS infrastructure to provide:

Global Edge Network: Automatic deployments to AWS edge locations for low-latency access worldwide
Serverless Functions: Automatic scaling of backend API functionality using AWS Lambda
Blob Storage: Secure document storage using Vercel Blob Storage, which is built on top of AWS S3
Preview Environments: Isolated environments for testing feature branches before production deployment
Performance Analytics: Real-time monitoring and performance metrics collection

Our team has been working extensively with Vercel to optimize the deployment pipeline, implement CI/CD workflows, and leverage its AWS-powered infrastructure for high availability and reliability. This has significantly improved our deployment velocity and application performance.

7. Technology Stack

Technology Stack

MongoDB Node.js React OAuth 2.0 REST API Next.js Vercel AWS

7.1 Core Business Services

The application implements several key business services through the Next.js API routes architecture:

Business Logic Services Architecture

Core services and their relationships within the application architecture.

flowchart TD classDef primaryService fill:#dbeafe,stroke:#3b82f6,stroke-width:2px classDef dataStore fill:#ede9fe,stroke:#8b5cf6,stroke-width:2px classDef external fill:#dcfce7,stroke:#10b981,stroke-width:2px Client([Client Browser]) subgraph NextjsApp["Next.js Application"] direction TB subgraph APIRoutes["API Routes"] ClientMgmt["Client Management Service"] DealEngine["Deal Management Engine"] TradingEngine["Trading Engine"] Disbursement["Disbursement Processor"] DocManagement["Document Management Service"] end subgraph FrontendPages["Frontend Pages"] OnboardingUI["Onboarding UI"] DealUI["Deal Management UI"] TradingUI["Trading Interface"] DocumentUI["Document Center"] DisbursementUI["Disbursement Dashboard"] end FrontendPages ---> APIRoutes end MongoDB[(MongoDB)] BlobStorage[(Vercel Blob Storage)] APIRoutes --> MongoDB DocManagement --> BlobStorage Client --> NextjsApp %% Service details with tooltips ClientMgmt-->|"Manages client data\nHandles onboarding workflow\nImplements risk profiling"| MongoDB DealEngine-->|"Core transactional engine\nStep-based progression\nApproval workflow"| MongoDB TradingEngine-->|"Trading verification\nExecution tracking\nPerformance monitoring"| MongoDB Disbursement-->|"Fund distribution\nTransaction recording\nApproval workflow"| MongoDB DocManagement-->|"Document metadata\nCategorization"| MongoDB ClientMgmt:::primaryService DealEngine:::primaryService TradingEngine:::primaryService Disbursement:::primaryService DocManagement:::primaryService MongoDB:::dataStore BlobStorage:::dataStore

Client Management Service

Implementation: /pages/api/steps/* and related endpoints

Manages the client onboarding workflow
Handles client data collection, validation, and persistence
Implements step-based journey from introduction to verification
Provides configuration-driven forms and workflows

Key Functions:

Client registration and onboarding
Client assessment including risk profiling
Client verification and objective assessment
Configuration-driven workflow management

Deal Management Engine

Implementation: /pages/api/deals/*

Core transactional engine for investment deals
Implements deal lifecycle from creation through approval
Manages state transitions and validation rules
Provides structured data model with step-based progression

Key Functions:

Deal creation with unique ID generation
Step management through the deal lifecycle
Status tracking and history recording
Deal approval workflow

Trading Engine

Implementation: Part of the deal workflow within /pages/api/deals/*

Implements the trading workflow for investment deals
Manages trading verification, execution, and documentation
Tracks trading strategy and performance

Key Functions:

Trading verification and prerequisite checks
Trading program definition and documentation
Trading execution and tracking
Trading performance monitoring

Disbursement Processor

Implementation: Components in /components/disbursement/* with API endpoints in /pages/api/disbursement/

Manages the distribution of funds to various parties
Implements disbursement calculations, verifications, and approvals
Handles transaction recording and documentation

Key Functions:

Disbursement calculation based on participation agreements
Transaction recording and documentation
Approval workflow for disbursements
Verification and compliance checks

Document Management Service

Implementation: /pages/api/documents/* and /pages/api/utils/storageService.ts

Handles document uploads, storage, retrieval, and deletion
Manages document metadata and categorization
Integrates with Vercel Blob Storage for document persistence

Key Functions:

Secure document upload with size validation
Document retrieval with appropriate content-type handling
Document deletion and lifecycle management
Path-based document organization

7.2 Data Flow Architecture

Client Request → API Route → Business Logic → Database → Response
Document Upload → API Route → Storage Service → Blob Storage → Metadata in Database → Response
Workflow Progression → API Route → State Validation → State Update → Event Recording → Response

Last Updated: