# pankajkumardev/flowpay architecture

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

- Interactive diagram: https://gitdiagram.com/pankajkumardev/flowpay
- Repository: https://github.com/pankajkumardev/flowpay

## Overview

##### Main Components
- Frontend Applications:
- user-app: The primary user interface with pages for dashboard, bank pages (HDFC, Axis), authentication, and more.
- merchant-app: Another Next.js–based app handling merchant related interfaces and possibly payment or transactional views.
- Backend Services:
- Bank-WebHook: Implements endpoints for receiving external webhook events. Also, note the future plans for Express integration.
- Next.js API routes in both user-app and merchant-app: These handle authentication (using NextAuth & JWT), money transfers, and wallet operations.
- Shared/Utility Packages:
- packages/db: Contains database logic/ORM (Prisma with PostgreSQL/NeonDB, migrations, and seeding).
- packages/ui: Reusable UI components.
- packages/store: State management logic (using Recoil or similar approaches).
- Other shared configuration packages (eslint-config, typescript-config) that enforce coding standards across the monorepo.
- External Services and Infrastructure:
- Database: PostgreSQL managed via Prisma.
- Authentication service: NextAuth, JWT based session management.
- Deployment Platforms: AWS EC2 for Docker-based deployments and Vercel for production-ready deployments.
- Future external integrations: Webhook endpoints (potential Express server) for communicating with external banks or notification systems.

##### Relationships and Data Flow
- Users interact with the frontend applications via browsers. The user-app and merchant-app serve distinct roles (user dashboard, transactions, merchant operations).
- Both frontend apps include API routes that connect to backend logic for authentication, fund transfers, and transaction management.
- The Bank-WebHook app is an independent service receiving callbacks or notifications (webhooks) from the banks’ simulated pages.
- All backend components use the packages/db module to interact with the PostgreSQL database through Prisma ORM.
- Shared packages (UI, store) are consumed by the frontend apps to maintain consistency in design and state management.
- API communication flows:
- Client ↔ Frontend app (Next.js pages/components)
- Frontend app ↔ Internal API endpoints (via Next.js API routes)
- API endpoints ↔ Database (using Prisma)
- Backend services (Bank-WebHook) may communicate with frontend apps or pull in data from the database when processing webhooks.
- Deployment and CI/CD pipelines (Docker configurations, GitHub workflows) ensure smooth deployment and continuous integration across apps.

##### Architectural Patterns and Design Principles
- Monorepo Structure with Turborepo: Useful for managing multiple apps and shared packages under one repository.
- Separation of Concerns: Clear division between frontend (UI applications) and backend (API handling, webhook processing, database operations).
- Modular Design: The use of shared packages for the db, UI, and store encourages reusability and consistency across the system.
- Secure and Scalable Communication: Emphasize NextAuth for authentication and JWT sessions, utilizing REST-like API endpoints for internal interactions.
- Modern Frontend Framework: Built on Next.js with TailwindCSS, supplemented with interactive elements from Framer Motion.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    client("Browser/Client"):::external

    %% Frontend Applications
    subgraph "Frontend Applications"
        userApp("user-app (Next.js, TailwindCSS)"):::frontend
        merchantApp("merchant-app (Next.js)"):::frontend
        userAPI("user-app API Routes<br/>(NextAuth,JWT)"):::backend
        merchantAPI("merchant-app API Routes<br/>(NextAuth,JWT)"):::backend
    end

    %% Backend Services
    subgraph "Backend Services"
        bankWebhook("Bank-WebHook<br/>(Webhook Endpoints)"):::backend
    end

    %% Shared Modules/Packages
    subgraph "Shared Modules"
        sharedDB("packages/db (Prisma ORM)"):::shared
        sharedUI("packages/ui (UI Components)"):::shared
        sharedStore("packages/store (State Management)"):::shared
    end

    %% External Systems and Infrastructure
    subgraph "External Systems"
        postgres("PostgreSQL (NeonDB)"):::external
        authService("Authentication<br/>(NextAuth,JWT)"):::external
        banks("Bank Pages<br/>(HDFC,Axis)"):::external
        deployment("Deployment<br/>(AWS EC2,Vercel)"):::external
    end

    %% Connections
    client -->|"HTTP_Request"| userApp
    client -->|"HTTP_Request"| merchantApp

    userApp -->|"Internal_Call"| userAPI
    merchantApp -->|"Internal_Call"| merchantAPI

    %% Frontend consumption of shared components
    userApp -->|"Uses"| sharedUI
    userApp -->|"Uses"| sharedStore
    merchantApp -->|"Uses"| sharedUI
    merchantApp -->|"Uses"| sharedStore

    %% API endpoints interacting with backend services and shared DB
    userAPI -->|"Queries/Mutates"| sharedDB
    merchantAPI -->|"Queries/Mutates"| sharedDB
    userAPI -->|"Auth_Validation"| authService
    merchantAPI -->|"Auth_Validation"| authService

    %% Shared DB connecting to external PostgreSQL
    sharedDB -->|"ORM_Access"| postgres

    %% Bank webhook interactions
    banks -->|"Sends_Webhook"| bankWebhook
    bankWebhook -->|"Updates_Data"| sharedDB

    %% Deployment (optional connections)
    userApp ---|"Deployed_On"| deployment
    merchantApp ---|"Deployed_On"| deployment
    bankWebhook ---|"Deployed_On"| deployment

    %% Click Events for Component Mapping
    click userApp "https://github.com/pankajkumardev/flowpay/tree/main/apps/user-app"
    click merchantApp "https://github.com/pankajkumardev/flowpay/tree/main/apps/merchant-app"
    click bankWebhook "https://github.com/pankajkumardev/flowpay/tree/main/apps/Bank-WebHook"
    click sharedDB "https://github.com/pankajkumardev/flowpay/tree/main/packages/db"
    click sharedUI "https://github.com/pankajkumardev/flowpay/tree/main/packages/ui"
    click sharedStore "https://github.com/pankajkumardev/flowpay/tree/main/packages/store"

    %% Styles
    classDef frontend fill:#a6d8ff,stroke:#1a73e8,stroke-width:2px;
    classDef backend fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef shared fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px;
    classDef external fill:#e1bee7,stroke:#8e24aa,stroke-width:2px;
```
