🚀 WalletX - Modern Digital Wallet Platform

A sophisticated, full-stack digital wallet platform inspired by Paytm, built with modern technologies in 5 days. Real money is not involved.

---

📋 Table of Contents

• ✨ Features
• 🛠️ Tech Stack
• 🏗️ Architecture
• 🚀 Quick Start
• 📁 Project Structure
• 🔧 API Documentation
• 🎨 UI/UX Features
• 🔒 Security Features
• 📊 Performance
• 🧪 Testing
• 📦 Deployment
• 🤝 Contributing
• 📄 License

---

✨ Features

💳 Core Wallet Features

• Instant Money Transfers - Real-time peer-to-peer transactions
• Secure Balance Management - Bank-grade security with encrypted storage
• Transaction History - Comprehensive audit trail with search and filtering
• Multi-Currency Support - INR, USD, ETH, BTC (extensible framework)
• Account Types - Wallet, Savings, and Trading accounts

🔐 Security & Authentication

• JWT-based Authentication - Secure token-based session management
• Password Hashing - BCrypt encryption with salt rounds
• Input Validation - Zod schema validation for all user inputs
• CORS Protection - Cross-origin resource sharing security
• Rate Limiting - Protection against brute force attacks

🎨 Modern UI/UX

• Responsive Design - Mobile-first approach with Tailwind CSS
• Dark/Light Mode - Theme switching with system preference detection
• Smooth Animations - Framer Motion powered micro-interactions
• Real-time Updates - Live balance and transaction updates
• Accessibility - WCAG 2.1 compliant components

📊 Analytics & Insights

• Balance Trends - Interactive charts with Recharts
• Transaction Analytics - Spending patterns and insights
• Real-time Dashboard - Live financial overview
• Export Capabilities - Transaction history export

---

🛠️ Tech Stack

Frontend

Technology	Version	Purpose
React	18.3.1	UI Framework
TypeScript	5.9.2	Type Safety
Vite	5.4.19	Build Tool & Dev Server
Tailwind CSS	3.4.17	Utility-First CSS
Framer Motion	12.23.12	Animation Library
React Router	6.30.1	Client-side Routing
Axios	1.11.0	HTTP Client
React Query	5.83.0	Server State Management
Radix UI	Latest	Accessible Components
Recharts	2.15.4	Data Visualization

Backend

Technology	Version	Purpose
Node.js	18+	Runtime Environment
Express.js	5.1.0	Web Framework
TypeScript	5.9.2	Type Safety
MongoDB	8.17.0	NoSQL Database
Mongoose	8.17.0	ODM for MongoDB
JWT	9.0.2	Authentication
BCrypt	6.0.0	Password Hashing
Zod	4.0.14	Schema Validation
CORS	2.8.5	Cross-Origin Security

Development Tools

• ESLint - Code linting and formatting
• Nodemon - Development server with auto-reload
• PostCSS - CSS processing
• Autoprefixer - CSS vendor prefixing

---

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │   Database      │
│   (React/TS)    │◄──►│   (Node/Express)│◄──►│   (MongoDB)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
    ┌────▼────┐            ┌─────▼─────┐            ┌────▼────┐
    │  Vite   │            │  Express  │            │ Mongoose│
    │  Dev    │            │  Server   │            │   ODM   │
    │ Server  │            │           │            │         │
    └─────────┘            └───────────┘            └─────────┘

System Architecture Highlights

• Microservices-Ready - Modular design for easy scaling
• RESTful API - Standard HTTP methods and status codes
• MVC Pattern - Clear separation of concerns
• Middleware Architecture - Extensible request processing
• Database Transactions - ACID compliance for financial operations

---

🚀 Quick Start

Prerequisites

• Node.js (v18 or higher)
• MongoDB (v6.0 or higher)
• npm or yarn package manager

Installation

1. Clone the repository

   git clone https://github.com/titanjagpreet/walletx.git
   cd walletx

2. Install dependencies

   # Install backend dependencies
   cd backend
   npm install
   
   # Install frontend dependencies
   cd ../frontend
   npm install

3. Environment Setup

   # Backend (.env)
   cd backend
   cp .env.example .env

   Configure your .env file:

   PORT=5000
   MONGO_URI=mongodb://localhost:27017/walletx
   JWT_SECRET=your-super-secret-jwt-key
   NODE_ENV=development

4. Database Setup

   # Start MongoDB (if not running)
   mongod
   
   # The application will automatically create collections

5. Start Development Servers

   # Terminal 1 - Backend
   cd backend
   npm run dev
   
   # Terminal 2 - Frontend
   cd frontend
   npm run dev

6. Access the Application

   • Frontend: http://localhost:5173
   • Backend API: http://localhost:5000
   • API Documentation: http://localhost:5000/api-docs

---

📁 Project Structure

walletx/
├── backend/                          # Backend API Server
│   ├── src/
│   │   ├── controller/              # Request handlers
│   │   │   ├── accountController.ts # Account operations
│   │   │   └── userController.ts    # User management
│   │   ├── middlewares/             # Express middlewares
│   │   │   ├── userValidation.ts    # Input validation
│   │   │   └── verifyJWT.ts         # JWT authentication
│   │   ├── models/                  # Database models
│   │   │   ├── db.ts               # Database connection
│   │   │   └── models.ts           # Mongoose schemas
│   │   ├── routes/                  # API routes
│   │   │   ├── accountRoutes.ts    # Account endpoints
│   │   │   └── userRoutes.ts       # User endpoints
│   │   ├── services/                # Business logic
│   │   │   └── transferFunds.ts    # Money transfer service
│   │   └── server.ts               # Express server setup
│   ├── package.json
│   └── tsconfig.json
│
├── frontend/                         # React Frontend
│   ├── src/
│   │   ├── components/              # Reusable UI components
│   │   │   ├── auth/               # Authentication components
│   │   │   ├── ui/                 # Base UI components
│   │   │   ├── FAQ.tsx            # FAQ section
│   │   │   ├── Features.tsx       # Features showcase
│   │   │   ├── Footer.tsx         # Footer component
│   │   │   ├── Hero.tsx           # Landing hero section
│   │   │   ├── HowItWorks.tsx     # How it works section
│   │   │   └── Navbar.tsx         # Navigation bar
│   │   ├── hooks/                  # Custom React hooks
│   │   ├── lib/                    # Utility functions
│   │   ├── pages/                  # Page components
│   │   │   ├── Dashboard.tsx      # Main dashboard
│   │   │   ├── Index.tsx          # Landing page
│   │   │   ├── NotFound.tsx       # 404 page
│   │   │   ├── SignIn.tsx         # Login page
│   │   │   └── SignUp.tsx         # Registration page
│   │   ├── App.tsx                # Main app component
│   │   ├── index.css              # Global styles
│   │   └── main.tsx               # App entry point
│   ├── package.json
│   └── vite.config.ts
│
└── README.md

---

🔧 API Documentation

Authentication Endpoints

POST /api/v1/users/signup

Create a new user account.

Request Body:

{
  "firstName": "John",
  "lastName": "Doe",
  "username": "johndoe",
  "email": "john@example.com",
  "password": "SecurePass123!"
}

Response:

{
  "message": "User signed up! Welcome John"
}

POST /api/v1/users/signin

Authenticate user and receive JWT token.

Request Body:

{
  "username": "johndoe",
  "password": "SecurePass123!"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "message": "User logged in. Welcome John"
}

Account Endpoints

GET /api/v1/account/balance

Get current account balance.

Headers:

Authorization: Bearer <jwt-token>

Response:

{
  "message": "Balance fetch successful",
  "balance": 1500.50
}

GET /api/v1/account/transactions

Get transaction history.

Headers:

Authorization: Bearer <jwt-token>

Response:

{
  "message": "Transactions fetched successfully",
  "transactions": [
    {
      "type": "sent",
      "user": "johndoe",
      "name": "John Doe",
      "amount": 100.00,
      "currency": "INR",
      "date": "2024-01-15T10:30:00Z",
      "status": "success",
      "note": "Payment for services"
    }
  ]
}

POST /api/v1/account/transfer

Transfer money to another user.

Headers:

Authorization: Bearer <jwt-token>

Request Body:

{
  "receiverUsername": "johndoe",
  "amount": 100.00
}

Response:

{
  "message": "Funds successfully transferred"
}

User Profile Endpoints

GET /api/v1/users/profile

Get user profile information.

PUT /api/v1/users/email

Update user email address.

PUT /api/v1/users/username

Update username.

---

🎨 UI/UX Features

Design System

• Modern FinTech Aesthetic - Professional, trustworthy design
• Responsive Grid System - Mobile-first responsive design
• Consistent Color Palette - Primary, secondary, and accent colors
• Typography Scale - Hierarchical text system
• Component Library - Reusable UI components

Interactive Elements

• Smooth Transitions - CSS transitions and Framer Motion animations
• Hover Effects - Interactive feedback on user actions
• Loading States - Skeleton screens and loading spinners
• Toast Notifications - User feedback for actions
• Form Validation - Real-time input validation

Accessibility

• Keyboard Navigation - Full keyboard accessibility
• Screen Reader Support - ARIA labels and semantic HTML
• Color Contrast - WCAG 2.1 AA compliance
• Focus Management - Proper focus indicators
• Reduced Motion - Respects user motion preferences

---

🔒 Security Features

Authentication & Authorization

• JWT Tokens - Secure, stateless authentication
• Token Expiration - Automatic token refresh mechanism
• Password Policies - Strong password requirements
• Account Lockout - Protection against brute force attacks

Data Protection

• Input Sanitization - XSS protection
• SQL Injection Prevention - Parameterized queries
• CORS Configuration - Controlled cross-origin access
• Rate Limiting - API abuse prevention

Financial Security

• Transaction Validation - Multi-layer transaction verification
• Balance Checks - Real-time balance validation
• Audit Trails - Complete transaction logging
• Fraud Detection - Suspicious activity monitoring

---

📊 Performance

Frontend Optimization

• Code Splitting - Dynamic imports for better loading
• Lazy Loading - Component-level code splitting
• Image Optimization - WebP format with fallbacks
• Bundle Analysis - Optimized bundle sizes
• Caching Strategy - Browser and CDN caching

Backend Performance

• Database Indexing - Optimized query performance
• Connection Pooling - Efficient database connections
• Response Caching - Redis-based caching layer
• Compression - Gzip response compression
• Load Balancing - Horizontal scaling support

Monitoring & Analytics

• Performance Metrics - Core Web Vitals tracking
• Error Tracking - Comprehensive error logging
• User Analytics - Usage pattern analysis
• Health Checks - System health monitoring

---

🧪 Testing

Frontend Testing

# Run unit tests
npm run test

# Run integration tests
npm run test:integration

# Run E2E tests
npm run test:e2e

Backend Testing

# Run unit tests
npm run test

# Run API tests
npm run test:api

# Run load tests
npm run test:load

Test Coverage

• Unit Tests - Component and function testing
• Integration Tests - API endpoint testing
• E2E Tests - Full user journey testing
• Performance Tests - Load and stress testing

---

📦 Deployment

Production Build

# Build frontend
cd frontend
npm run build

# Build backend
cd backend
npm run build

Environment Variables

# Production
NODE_ENV=production
PORT=5000
MONGO_URI=mongodb://production-db:27017/walletx
JWT_SECRET=production-jwt-secret
CORS_ORIGIN=https://walletx.com

Deployment Platforms

• Frontend - Vercel, Netlify, or AWS S3
• Backend - Heroku, AWS EC2, or Google Cloud
• Database - MongoDB Atlas/Compass or AWS DocumentDB
• CDN - Cloudflare or AWS CloudFront

Docker Deployment

# Build and run with Docker
docker-compose up -d

# Or build individual containers
docker build -t walletx-frontend ./frontend
docker build -t walletx-backend ./backend

---

🤝 Contributing

We welcome contributions from the community! Please read our contributing guidelines.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and add tests
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Code Standards

• TypeScript - Strict type checking enabled
• ESLint - Consistent code formatting
• Prettier - Automatic code formatting
• Conventional Commits - Standard commit message format

Testing Requirements

• Unit Tests - Minimum 80% coverage
• Integration Tests - All API endpoints covered
• E2E Tests - Critical user flows tested

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Paytm - Inspiration for the wallet concept
• React Team - Amazing frontend framework
• Node.js Community - Robust backend ecosystem
• MongoDB - Flexible NoSQL database
• Tailwind CSS - Utility-first CSS framework

---

📞 Support

• Issues - GitHub Issues
• Discussions - GitHub Discussions

---

**Made with ❤️ by Jagpreet **