# 86pushkar24/finconnect architecture

> Architecture diagram of the GitHub repository 86pushkar24/finconnect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/86pushkar24/finconnect
- Repository: https://github.com/86pushkar24/finconnect

## Overview

##### Project type and purpose
- Project Type: Full‑stack SaaS web application built with Next.js 13 (App Router), TypeScript, and TailwindCSS.
- Purpose: A fintech platform (“FinConnect”) that lets users securely authenticate, link multiple bank accounts via Plaid, view balances/transactions, and transfer funds between users via Dwolla. Data persistence and user management use Appwrite.

##### File structure
- Top‑level Next.js “app/” directory houses all routes and layouts:
- app/(auth): Sign‑in and Sign‑up pages (SSR, server actions).
- app/(root): Authenticated area – pages for dashboard (overview), My Banks, Transaction History, Payment Transfer.
- app/api: Example API route (sentry).
- “components/”: Reusable UI pieces (BankCard, Sidebar, Charts, Forms, UI primitives under components/ui).
- “lib/”: Server‑side actions and utilities:
- appwrite.ts – sets up Appwrite clients.
- plaid.ts – configures Plaid SDK.
- dwolla.actions.ts, bank.actions.ts, transaction.actions.ts, user.actions.ts – encapsulate calls to external services and database.
- “constants/” and “types/”: Shared constants and TypeScript types.
- Config files: next.config.mjs, tailwind.config.ts, tsconfig.json, Sentry configs, ESLint, PostCSS.

##### Key insights from the README
- Tech stack: Next.js (SSR & server actions), TypeScript, Appwrite (DB & Auth), Plaid (bank linking & transactions), Dwolla (fund transfers), Chart.js, React Hook Form + Zod, TailwindCSS, ShadCN UI.
- Core features: Authentication, Bank Linking, Real‑time Balances, Transaction History with pagination, Funds Transfer.

a. Main Components
- Client Browser (React UI)
- Next.js Server
- Page Routes & Layouts (app/)
- Server Actions & API Routes (lib/actions, app/api)
- Database & Auth: Appwrite service (Users, Banks, Transactions collections)
- External Financial APIs:
- Plaid – Link Token, Transactions Sync, Accounts API, Institution API
- Dwolla – Customer Creation, Funding Source, Transfers
- Monitoring: Sentry (client, server, edge)
- Static Assets & CDN (public/, Next.js asset handling)
b. Relationships & Data Flows
1. User Authentication:
Browser → Next.js Server → Appwrite Authentication API → Session Cookie
2. Bank Linking:
Browser (Plaid Link widget) ↔ Plaid Link API
Browser → Next.js Server (exchangePublicToken) → Plaid API → Dwolla API → Appwrite (store bank document)
3. Data Retrieval:
Browser → Next.js Server (server actions) → Appwrite (get bank list) + Plaid (accountsGet, transactionsSync) → Server → Browser
4. Funds Transfer:
Browser (PaymentTransferForm) → Next.js Server (createTransfer) → Dwolla API → Next.js Server (createTransaction) → Appwrite
5. Monitoring & Errors:
Any component → Sentry (client or server)
c. Architectural Patterns & Principles
- App Router with hierarchical layouts (app/(auth), app/(root))
- Server Actions for data fetching & mutations (colocated in lib/actions)
- Separation of concerns: UI components vs. service‑layer actions
- Externalization of secrets and environment variables (.env)
- Declarative styling with TailwindCSS and ShadCN
d. Key Technologies & Frameworks
- Next.js (App Router, Server Actions, SSR, API routes)
- TypeScript
- Appwrite (Database, Auth)
- Plaid SDK
- Dwolla‑V2 SDK
- React Hook Form + Zod (forms & validation)
- Chart.js
- TailwindCSS + ShadCN UI
- Sentry

##### Detailed but Concise
- Essential layers: Client → Next.js → External APIs → Database.
- Every major folder or module (UI, server actions, config).
- How data moves end‑to‑end for key flows (auth, link, fetch, transfer).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Browser["Client Browser"]:::frontend

    %% Next.js Server
    subgraph "Next.js Server" 
        direction TB
        subgraph "Routing & Pages (app/)"
            direction TB
            AuthLayout["Auth Layout"]:::frontend
            SignInPage["Sign-In Page"]:::frontend
            SignUpPage["Sign-Up Page"]:::frontend
            RootLayout["Root Layout"]:::frontend
            DashboardPage["Dashboard Page"]:::frontend
            MyBanksPage["My Banks Page"]:::frontend
            TransactionHistoryPage["Transaction History Page"]:::frontend
            PaymentTransferPage["Payment Transfer Page"]:::frontend
        end

        subgraph "Server Actions & Config (lib/)"
            direction TB
            AppwriteConfig["Appwrite Client Config"]:::backend
            PlaidConfig["Plaid SDK Config"]:::backend
            BankActions["Bank Actions"]:::backend
            DwollaActions["Dwolla Actions"]:::backend
            TransactionActions["Transaction Actions"]:::backend
            UserActions["User Actions"]:::backend
        end

        subgraph "API Routes (app/api)"
            direction TB
            SentryAPI["Sentry API Route"]:::backend
        end

        subgraph "Global Styles & Layouts"
            direction TB
            GlobalsCSS["Globals CSS"]:::static
            AppLayout["App Layout"]:::frontend
        end
    end

    %% External Services & Databases
    AppwriteDB["Appwrite Auth & Database"]:::external
    PlaidAPI["Plaid API"]:::external
    DwollaAPI["Dwolla API"]:::external
    CDN["Static Assets & CDN"]:::static
    Sentry["Sentry Monitoring"]:::external

    %% Flows
    Browser -->|visits auth| AuthLayout
    AuthLayout -->|renders| SignInPage
    AuthLayout -->|renders| SignUpPage
    SignInPage -->|server action| UserActions
    SignUpPage -->|server action| UserActions
    UserActions -->|Auth API| AppwriteDB
    AppwriteDB -->|session cookie| Browser

    Browser -->|visits app| RootLayout
    RootLayout -->|renders| DashboardPage
    RootLayout -->|renders| MyBanksPage
    RootLayout -->|renders| TransactionHistoryPage
    RootLayout -->|renders| PaymentTransferPage

    %% Bank Linking Flow
    Browser -->|Plaid Link UI| PlaidAPI
    Browser -->|exchange token| PlaidConfig
    PlaidConfig -->|accounts & institutions| PlaidAPI
    PlaidConfig -->|store bank| BankActions
    BankActions -->|DB write| AppwriteDB

    %% Data Retrieval
    Browser -->|server action| BankActions
    BankActions -->|read banks| AppwriteDB
    Browser -->|server action| TransactionActions
    TransactionActions -->|read tx| AppwriteDB
    TransactionActions -->|sync tx| PlaidAPI

    %% Funds Transfer
    Browser -->|transfer form| DwollaActions
    DwollaActions -->|Dwolla Customer & Transfers| DwollaAPI
    DwollaActions -->|record tx| TransactionActions
    TransactionActions -->|write tx| AppwriteDB

    %% API Routes & Monitoring
    Browser -->|calls| SentryAPI
    SentryAPI -->|reports| Sentry
    UserActions -->|error| Sentry
    BankActions -->|error| Sentry
    TransactionActions -->|error| Sentry
    DwollaActions -->|error| Sentry

    %% Static Assets
    Browser -->|assets| CDN
    CDN -->|serves| Browser

    %% Click Events
    click SignInPage "https://github.com/86pushkar24/finconnect/blob/main/app/(auth)/sign-in/page.tsx"
    click SignUpPage "https://github.com/86pushkar24/finconnect/blob/main/app/(auth)/sign-up/page.tsx"
    click AuthLayout "https://github.com/86pushkar24/finconnect/blob/main/app/(auth)/layout.tsx"
    click RootLayout "https://github.com/86pushkar24/finconnect/blob/main/app/(root)/layout.tsx"
    click DashboardPage "https://github.com/86pushkar24/finconnect/blob/main/app/(root)/page.tsx"
    click MyBanksPage "https://github.com/86pushkar24/finconnect/blob/main/app/(root)/my-banks/page.tsx"
    click TransactionHistoryPage "https://github.com/86pushkar24/finconnect/blob/main/app/(root)/transaction-history/page.tsx"
    click PaymentTransferPage "https://github.com/86pushkar24/finconnect/blob/main/app/(root)/payment-transfer/page.tsx"
    click SentryAPI "https://github.com/86pushkar24/finconnect/blob/main/app/api/sentry-example-api/route.js"
    click AppwriteConfig "https://github.com/86pushkar24/finconnect/blob/main/lib/appwrite.ts"
    click PlaidConfig "https://github.com/86pushkar24/finconnect/blob/main/lib/plaid.ts"
    click BankActions "https://github.com/86pushkar24/finconnect/blob/main/lib/actions/bank.actions.ts"
    click DwollaActions "https://github.com/86pushkar24/finconnect/blob/main/lib/actions/dwolla.actions.ts"
    click TransactionActions "https://github.com/86pushkar24/finconnect/blob/main/lib/actions/transaction.actions.ts"
    click UserActions "https://github.com/86pushkar24/finconnect/blob/main/lib/actions/user.actions.ts"

    %% Styles
    classDef frontend fill:#cce4f6,stroke:#0366d6,color:#0366d6
    classDef backend fill:#e6f4ea,stroke:#22863a,color:#22863a
    classDef external fill:#f0f0f0,stroke:#6a737d,color:#6a737d
    classDef static fill:#f5f5f5,stroke:#d1d5da,color:#6a737d
    class SignInPage,SignUpPage,AuthLayout,RootLayout,DashboardPage,MyBanksPage,TransactionHistoryPage,PaymentTransferPage,AppLayout frontend
    class AppwriteConfig,PlaidConfig,BankActions,DwollaActions,TransactionActions,UserActions,SentryAPI backend
    class AppwriteDB,PlaidAPI,DwollaAPI,Sentry external
    class GlobalsCSS,CDN static
```
