# shiva-gsk/digiwallet-mcp architecture

> Architecture diagram of the GitHub repository shiva-gsk/digiwallet-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shiva-gsk/digiwallet-mcp
- Repository: https://github.com/shiva-gsk/digiwallet-mcp

## Overview

##### Project type and purpose
- This is a full-stack web application called “Digital Wallet Management System” built on Next.js (app directory), Tailwind CSS, Node.js + Prisma, and PostgreSQL. It provides user-facing wallet UI, admin dashboards, serverless API routes, business logic actions, and integrates external services (Clerk, Stripe, Resend).

##### File structure
- Top-level “digiwallet” directory contains:
- app/ – Next.js app directory including pages (React server/client components) and server actions under app/actions, plus API routes under app/api
- components/ – UI components organized by feature and a shared ui/ subfolder
- lib/ – low-level helpers (db client, utils)
- models/ – SQL schema, queries, Prisma schema
- prisma/ – Prisma schema definition
- utils/ – cross-cutting services (emailService, OTP)
- middleware.ts, next.config.ts – global config
- “mcp” directory holds a separate Python microservice (Flask or similar), suggesting an auxiliary processing component.

##### Extract architecture details from the README
- Frontend: Next.js, responsive pages
- Backend: Node.js + Prisma ORM connecting to Neon/PostgreSQL
- Auth: Clerk (OAuth, email/MFA) with webhook handling
- Payments: Stripe (create-payment-intent route)
- Email: Resend service for notifications
- Hosting: Vercel serverless functions

##### Main components and how to represent them
a. Client / Browser / Mobile (Users)
- Interacts via HTTPS with Next.js frontend
b. Next.js Frontend Layer (Vercel)
- app/layout.tsx, page.tsx (React Server/Client components)
- UI Components (components/…)
- Server Actions (app/actions/*.ts) for data mutations/fetches
- API Routes (app/api/*/route.ts) for webhooks, payments, password resets
c. Business Logic Layer
- Actions (depositMoney, sendMoney, getTransactions, etc.)
- Utilities (lib/utils.ts, otpService.js, emailService.js)
- Middleware (middleware.ts) for authentication/authorization
d. Data Access Layer
- Prisma Client (lib/db.ts)
- SQL queries (models/sqlQueries/*.ts)
- Prisma schema (prisma/schema.prisma)
e. Database
- PostgreSQL (Neon)
f. External Services
- Clerk Auth Service (OAuth, user management, webhooks)
- Stripe Payments (create-payment-intent)
- Resend Email Service
g. Auxiliary Python Microservice (“mcp”)
- app.py, req.py: separate service possibly for batch processing or analytics
- Communicates over HTTP or message queue to main backend

##### Relationships & interactions
- User → Next.js Frontend (HTTPS)
- Frontend Server Components & Client Components call Server Actions & API Routes
- Server Actions & API Routes → Prisma Client → PostgreSQL
- API Routes → External Services (Clerk Webhooks, Stripe API, Resend API)
- External events (Clerk webhooks) → API route `/api/webhooks/clerk/route.ts`
- Python microservice (“mcp”) ↔ HTTP API endpoints on Next.js or direct DB access (as per design)
- Vercel hosts Next.js serverless functions and static assets

##### Architectural patterns & design principles
- Serverless functions for backend logic (Next.js API routes)
- Separation of concerns:
- Presentation (components/ + app/pages)
- Business logic (app/actions + utils)
- Data access (lib/db + models)
- Use of React Server Components and Client Components in Next.js 13 app directory
- Modular SQL queries for maintainability
- Middleware layer for auth enforcement
- Integration points for third-party services (Auth, Payments, Email)

##### Final advice
- Be thorough: break down into UI, server actions, API routes, data access, and external integrations
- Moving parts (webhooks, payments, email, auth)
- In layers for readability and show dependencies clearly

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        Layout["Next.js Layout"]:::frontend
        HomePage["Home Page"]:::frontend
        WalletPage["User Wallet Page"]:::frontend
        DepositPage["Deposit Page"]:::frontend
        SendMoneyPage["Send Money Page"]:::frontend
        AdminDashboard["Admin Dashboard Page"]:::frontend
        AdminUserDetails["Admin User Details Page"]:::frontend
        UIShared["UI Components (shared)"]:::frontend
        UIFeature["UI Components (feature)"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer" 
        direction TB
        Middleware["Middleware (auth)"]:::backend
        subgraph "Server Actions"
            direction TB
            SA_deposit["depositMoney"]:::backend
            SA_send["sendMoney"]:::backend
            SA_getTx["getTransactions"]:::backend
            SA_other["Other Actions"]:::backend
        end
        subgraph "API Routes"
            direction TB
            API_payIntent["Create Payment Intent API"]:::backend
            API_resetPwd["Password Reset API"]:::backend
            API_clerk["Clerk Webhooks API"]:::backend
        end
        Utils["Utility Functions"]:::backend
        EmailService["Email Service (Resend)"]:::backend
        OTPService["OTP Service"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        PrismaClient["Prisma Client"]:::backend
        SQLQueries["SQL Queries"]:::backend
        PrismaSchema["Prisma Schema"]:::backend
        DB["PostgreSQL Database"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Clerk["Clerk Auth Service"]:::external
        Stripe["Stripe Payments"]:::external
        Resend["Resend Email Service"]:::external
    end

    %% Microservice
    subgraph "MCP Service (Python)"
        direction TB
        MCPApp["app.py"]:::micro
        MCPReq["req.py"]:::micro
        MCPTest["test.py"]:::micro
        MCPData["data.json"]:::micro
    end

    %% User Interaction
    User["User (Browser/Mobile)"]:::external
    User --> HomePage
    User --> WalletPage
    User --> DepositPage
    User --> SendMoneyPage
    User --> AdminDashboard
    User --> AdminUserDetails

    %% Presentation to Components
    HomePage --> UIShared
    WalletPage --> UIShared
    DepositPage --> UIFeature
    SendMoneyPage --> UIFeature
    AdminDashboard --> UIFeature
    AdminUserDetails --> UIFeature

    %% Presentation to Application
    HomePage --> Middleware
    WalletPage --> SA_getTx
    DepositPage --> SA_deposit
    SendMoneyPage --> SA_send
    AdminDashboard --> API_clerk
    AdminUserDetails --> API_clerk

    %% API Routes interactions
    DepositPage --> API_payIntent
    SendMoneyPage --> API_payIntent
    HomePage --> API_resetPwd

    %% Middleware flows
    Middleware --> SA_other

    %% Server Actions & API to Data Layer
    SA_deposit --> PrismaClient
    SA_send --> PrismaClient
    SA_getTx --> PrismaClient
    SA_other --> PrismaClient
    API_payIntent --> PrismaClient
    API_resetPwd --> PrismaClient
    API_clerk --> PrismaClient

    PrismaClient --> DB
    SQLQueries --> DB
    PrismaSchema --> PrismaClient

    %% Application Utilities
    SA_deposit --> Utils
    SA_send --> Utils
    SA_other --> Utils
    Utils --> OTPService
    API_resetPwd --> EmailService

    %% External integrations
    API_clerk --> Clerk
    API_payIntent --> Stripe
    API_resetPwd --> Resend
    Clerk --> API_clerk

    %% Microservice interactions
    MCPApp --> API_payIntent
    MCPApp --> API_clerk
    MCPApp --> DB
    MCPReq --> MCPApp
    MCPTest --> MCPApp
    MCPData --> MCPApp

    %% Click Events
    click Layout "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/app/layout.tsx"
    click HomePage "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/app/page.tsx"
    click WalletPage "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/app/wallet/page.tsx"
    click DepositPage "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/app/wallet/deposit/page.tsx"
    click SendMoneyPage "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/app/send-money/page.tsx"
    click AdminDashboard "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/app/admin/page.tsx"
    click AdminUserDetails "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/app/admin/users/[id]/page.tsx"
    click UIShared "https://github.com/shiva-gsk/digiwallet-mcp/tree/master/digiwallet/components/ui"
    click UIFeature "https://github.com/shiva-gsk/digiwallet-mcp/tree/master/digiwallet/components"
    click SA_deposit "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/app/actions/depositMoney.ts"
    click SA_send "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/app/actions/sendMoney.tsx"
    click SA_getTx "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/app/actions/getTransactions.ts"
    click API_payIntent "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/app/api/create-payment-intent/route.ts"
    click API_resetPwd "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/app/api/reset-password/route.ts"
    click API_clerk "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/app/api/webhooks/clerk/route.ts"
    click Middleware "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/middleware.ts"
    click PrismaClient "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/lib/db.ts"
    click Utils "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/lib/utils.ts"
    click EmailService "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/utils/emailService.js"
    click OTPService "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/utils/otpService.js"
    click SQLQueries "https://github.com/shiva-gsk/digiwallet-mcp/tree/master/digiwallet/models/sqlQueries"
    click PrismaSchema "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/digiwallet/prisma/schema.prisma"
    click MCPApp "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/mcp/app.py"
    click MCPReq "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/mcp/req.py"
    click MCPTest "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/mcp/test.py"
    click MCPData "https://github.com/shiva-gsk/digiwallet-mcp/blob/master/mcp/data.json"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#0288D1,stroke-width:1px
    classDef backend fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px
    classDef db fill:#FFF3E0,stroke:#EF6C00,stroke-width:1px
    classDef external fill:#F3E5F5,stroke:#8E24AA,stroke-width:1px
    classDef micro fill:#ECEFF1,stroke:#546E7A,stroke-width:1px
```
