# youssef68oubenhamou/bank-system architecture

> Architecture diagram of the GitHub repository youssef68oubenhamou/bank-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/youssef68oubenhamou/bank-system
- Repository: https://github.com/youssef68oubenhamou/bank-system

## Overview

##### Project type and purpose
- This is a full-stack Next.js banking system (frontend + backend in one repo) that provides user authentication, account management, transaction history, money transfers, an admin panel, real-time chat/AI services, and integrates with external services (Plaid, Dwolla, Appwrite).

##### File structure
- Top-level “app” folder: Next.js App Router pages and layouts
- “(auth)” subfolder: login/signup flows
- “(root)” subfolder: authenticated routes (dashboard, my-banks, payment-transfer, transaction-history, chat-room, ai-service)
- “app/api”: Next.js API routes for chat, message history, AI generation, bank management, etc.
- “components” + “components/ui”: reusable React components and UI primitives
- “context/SocketContext.tsx” + “components/SocketProvider.tsx”: WebSocket wrapper for real-time chat
- “lib/…”: business logic modules (Plaid, Dwolla, Appwrite, AI intent detection, socket utilities, actions)
- “server.ts”: custom server entry (possibly for WebSockets)
- Config files: next.config.ts, tsconfig.json, tailwind.config.js, sentry configs

##### README for additional insights
- Tech stack: Next.js, MongoDB, Appwrite
- Features: user management (JWT or sessions), account/transaction CRUD, money transfer with validation, admin panel
- Third-party integrations: Plaid (bank data), Dwolla (payment rails), Appwrite (authentication/storage), Sentry (error monitoring)

a. Main Components
- Client (Browser/Mobile): Next.js React components, pages, UI, SocketProvider
- Next.js Server (SSR/SSR endpoints & API Lambdas): “app/api” routes + “server.ts” for WebSockets
- Business Logic Layer (“lib” modules + actions): Plaid, Dwolla, Appwrite wrappers, transaction logic, AI intent detection
- Database: MongoDB (accounts, users, transactions, chat history)
- Real-Time Layer: WebSocket server (context + socket.ts)
- External Services: Plaid API, Dwolla API, Appwrite Auth/Storage, OpenAI or other AI service, Sentry monitoring
- Admin UI: restricted Next.js pages + API endpoints for user/account management

b. Relationships & Data Flows
1. Client → Next.js Server: page rendering requests (SSR/SSG) & API calls (/api/chat, /api/messages, /api/generate, /api/groq, etc.)
2. Next.js API → Business Logic → Database: CRUD on user/accounts/transactions/chat
3. Business Logic → External Services:
– Plaid: fetching bank data
– Dwolla: executing transfers
– Appwrite: user auth, file storage (if used)
– AI Service: generating AI responses in “ai-service” route
4. Client ↔ WebSocket Server: real-time chat messages, presence
5. Errors/Instrumentation → Sentry (edge & server configs)

c. Architectural Patterns & Design Principles
- Separation of concerns:
– UI Components vs. Page Layouts vs. API Routes
– “lib” folder for business logic decoupled from React components
– “context” for stateful cross-cutting concerns (WebSockets)
- Modularization: each feature (chat, transfer, history) has its own API route + UI page
- Serverless functions: Next.js API routes as Lambdas, with custom server.ts for WebSockets
- Layered architecture:
– Presentation (client React)
– API / Controller (Next.js routes)
– Service / Business logic (lib/actions, lib/ai-tools)
– Data (MongoDB collections)

d. Key Technologies & Frameworks
- Next.js App Router (app/ folder)
- React + Tailwind CSS + custom UI primitives
- WebSocket (socket.io or native) via SocketProvider
- MongoDB (or Appwrite Database)
- Plaid & Dwolla SDKs
- Appwrite for auth & storage
- OpenAI or similar AI generative API
- Sentry for error monitoring

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Client Layer
  subgraph "Client (Browser)" 
    AuthUI["Auth Pages"]:::frontend
    UIComponents["UI Components"]:::frontend
    DashboardPage["Dashboard Page"]:::frontend
    DashboardLayout["Dashboard Layout"]:::frontend
    Sidebar["Sidebar Component"]:::frontend
    HeaderBox["HeaderBox Component"]:::frontend
    TotalBalanceBox["TotalBalanceBox Component"]:::frontend
    BankMgmtUI["Bank Management Page"]:::frontend
    TransactionUI["Transaction History Page"]:::frontend
    TransferUI["Payment Transfer Page"]:::frontend
    ChatListUI["Chat Room List Page"]:::frontend
    ChatDetailUI["Chat Detail Page"]:::frontend
    AIUI["AI Service Page"]:::frontend
  end

  %% Server Layer
  subgraph "Server (Cloud)" 
    subgraph "Next.js Server & API" 
      SSRAPI["Next.js SSR / API Routes"]:::backend
      APIRoutes["Next.js API Routes"]:::backend
    end
    subgraph "Business Logic Services"
      AppwriteLib["Appwrite SDK"]:::service
      PlaidLib["Plaid SDK"]:::service
      DwollaLib["Dwolla SDK"]:::service
      AItools["AI Tools"]:::service
      IntentDetect["Intent Detection"]:::service
      SocketUtil["Socket Utilities"]:::service
      TransactionActions["Transaction Actions"]:::service
      ReportActions["Report Actions"]:::service
    end
    MongoDB[(MongoDB)]:::db
    WebSocketServer["WebSocket Server"]:::backend
    subgraph "External Services"
      PlaidAPI["Plaid API"]:::external
      DwollaAPI["Dwolla API"]:::external
      AppwriteAuth["Appwrite Auth/Storage"]:::external
      OpenAI["OpenAI AI Service"]:::external
      Sentry["Sentry Monitoring"]:::infra
    end
  end

  %% Data Flows
  AuthUI -->|renders /api calls| SSRAPI
  UIComponents --> SSRAPI
  DashboardPage --> SSRAPI
  DashboardLayout --> SSRAPI
  Sidebar --> DashboardPage
  HeaderBox --> DashboardPage
  TotalBalanceBox --> DashboardPage
  BankMgmtUI --> SSRAPI
  TransactionUI --> SSRAPI
  TransferUI --> SSRAPI
  ChatListUI --> SSRAPI
  ChatDetailUI --> SSRAPI
  AIUI --> SSRAPI

  SSRAPI -->|uses| AppwriteLib
  SSRAPI -->|uses| PlaidLib
  SSRAPI -->|uses| DwollaLib
  SSRAPI -->|uses| AItools
  SSRAPI -->|uses| IntentDetect
  SSRAPI -->|uses| SocketUtil
  SSRAPI -->|invokes| TransactionActions
  SSRAPI -->|invokes| ReportActions

  TransactionActions --> MongoDB
  ReportActions --> MongoDB
  AppwriteLib --> MongoDB
  PlaidLib --> PlaidAPI
  DwollaLib --> DwollaAPI
  AItools --> OpenAI
  IntentDetect --> OpenAI

  WebSocketServer <-->|real-time messages| ChatListUI
  WebSocketServer <-->|real-time messages| ChatDetailUI
  WebSocketServer --> SocketUtil

  SSRAPI -->|errors| Sentry
  WebSocketServer -->|errors| Sentry

  %% Click Events
  click AuthUI "https://github.com/youssef68oubenhamou/bank-system/tree/main/app/(auth)"
  click UIComponents "https://github.com/youssef68oubenhamou/bank-system/tree/main/components/"
  click DashboardPage "https://github.com/youssef68oubenhamou/bank-system/blob/main/app/(root)/page.tsx"
  click DashboardLayout "https://github.com/youssef68oubenhamou/bank-system/blob/main/app/(root)/layout.tsx"
  click Sidebar "https://github.com/youssef68oubenhamou/bank-system/blob/main/components/Sidebar.tsx"
  click HeaderBox "https://github.com/youssef68oubenhamou/bank-system/blob/main/components/HeaderBox.tsx"
  click TotalBalanceBox "https://github.com/youssef68oubenhamou/bank-system/blob/main/components/TotalBalanceBox.tsx"
  click BankMgmtUI "https://github.com/youssef68oubenhamou/bank-system/blob/main/app/(root)/my-banks/page.tsx"
  click PlaidLib "https://github.com/youssef68oubenhamou/bank-system/blob/main/lib/plaid.ts"
  click TransactionUI "https://github.com/youssef68oubenhamou/bank-system/blob/main/app/(root)/transaction-history/page.tsx"
  click TransactionActions "https://github.com/youssef68oubenhamou/bank-system/blob/main/lib/actions/transaction.actions.ts"
  click ReportActions "https://github.com/youssef68oubenhamou/bank-system/blob/main/lib/actions/report.actions.ts"
  click TransferUI "https://github.com/youssef68oubenhamou/bank-system/blob/main/app/(root)/payment-transfer/page.tsx"
  click DwollaLib "https://github.com/youssef68oubenhamou/bank-system/blob/main/lib/actions/dwolla.actions.ts"
  click ChatListUI "https://github.com/youssef68oubenhamou/bank-system/blob/main/app/(root)/chat-room/page.tsx"
  click ChatDetailUI "https://github.com/youssef68oubenhamou/bank-system/blob/main/app/(root)/chat-room/[chatId]/page.tsx"
  click SocketUtil "https://github.com/youssef68oubenhamou/bank-system/blob/main/lib/socket.ts"
  click WebSocketServer "https://github.com/youssef68oubenhamou/bank-system/blob/main/server.ts"
  click AIUI "https://github.com/youssef68oubenhamou/bank-system/blob/main/app/(root)/ai-service/page.tsx"
  click AItools "https://github.com/youssef68oubenhamou/bank-system/blob/main/lib/ai-tools.ts"
  click IntentDetect "https://github.com/youssef68oubenhamou/bank-system/blob/main/lib/intent/detectChatIntent.ts"

  %% Styles
  classDef frontend fill:#cce5ff,stroke:#0366d6,color:#0366d6;
  classDef backend fill:#d4edda,stroke:#155724,color:#155724;
  classDef service fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
  classDef db fill:#f8d7da,stroke:#721c24,color:#721c24;
  classDef external fill:#fff3cd,stroke:#856404,color:#856404;
  classDef infra fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
