Payment Soundbox - AI-Powered Payment System

A modern, AI-powered payment soundbox application built with Next.js frontend and Express.js backend. This system provides dynamic QR code generation, real-time payment processing, and Text-to-Speech (TTS) announcements for payment confirmations.

🚀 Features

Frontend (Next.js)

• Modern UI: Beautiful, responsive interface with dark theme
• QR Code Generation: Dynamic QR codes for payment transactions
• Real-time Updates: Live payment status updates via WebSocket
• TTS Integration: Browser-based Text-to-Speech announcements
• Payment Dashboard: Analytics and transaction history
• Payment Status Display: Real-time payment status monitoring

Backend (Express.js)

• RESTful API: Complete payment management system
• WebSocket Support: Real-time communication with frontend
• SQLite Database: Persistent storage for payments and logs
• QR Code Generation: Server-side QR code creation
• TTS Integration: Text-to-Speech announcement system
• Payment Analytics: Comprehensive reporting and analytics
• Webhook Simulation: Payment confirmation simulation

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │   Database      │
│   (Next.js)     │◄──►│   (Express.js)  │◄──►│   (SQLite)      │
│                 │    │                 │    │                 │
│ • React UI      │    │ • REST API      │    │ • Payments      │
│ • WebSocket     │    │ • WebSocket     │    │ • Logs          │
│ • TTS Client    │    │ • QR Generation │    │ • TTS History   │
│ • State Mgmt    │    │ • TTS Server    │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

🛠️ Technology Stack

Frontend

• Next.js 16 - React framework
• TypeScript - Type safety
• Tailwind CSS - Styling
• Radix UI - Component library
• WebSocket - Real-time communication
• Web Speech API - Text-to-Speech

Backend

• Express.js - Web framework
• Node.js - Runtime environment
• SQLite3 - Database
• WebSocket - Real-time communication
• QRCode - QR code generation
• CORS - Cross-origin resource sharing

📦 Installation

Prerequisites

• Node.js 18+
• npm or pnpm

Setup

1. Clone the repository

git clone <repository-url>
cd payment-soundbox

2. Install dependencies

npm install
# or
pnpm install

3. Start the development servers

Terminal 1 - Backend Server:

npm run dev:server

Terminal 2 - Frontend Server:

npm run dev

4. Access the application

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001
• Health Check: http://localhost:3001/api/health

🚀 Quick Start

1. Create a Payment

1. Open the frontend application
2. Navigate to the QR Code Generator
3. Enter customer name and amount
4. Click "Generate QR Code"

2. Simulate Payment

1. Use the backend integration example
2. Click "Create Payment" to generate a test payment
3. Click "Confirm" to simulate payment confirmation
4. Listen for the TTS announcement

3. Test TTS

1. Click "Test TTS" to trigger a test announcement
2. Use "Simulate Payment" for a complete payment flow with TTS

📡 API Endpoints

Payments

• GET /api/payments - Get all payments
• POST /api/payments - Create new payment
• GET /api/payments/:id - Get payment by ID
• POST /api/payments/:id/confirm - Confirm payment
• POST /api/payments/:id/fail - Mark payment as failed
• GET /api/payments/analytics/summary - Get analytics

QR Codes

• POST /api/qr/generate - Generate QR code
• POST /api/qr/scan - Scan QR code
• POST /api/qr/validate - Validate QR code
• GET /api/qr/info/:paymentId - Get QR info

TTS

• POST /api/tts/announce - Trigger TTS announcement
• POST /api/tts/test - Test TTS functionality
• POST /api/tts/simulate-payment - Simulate payment with TTS
• GET /api/tts/status - Get TTS system status

Health

• GET /api/health - Server health check

🔌 WebSocket Events

The system broadcasts real-time events:

• payment_created - New payment created
• payment_confirmed - Payment confirmed
• payment_failed - Payment failed
• qr_generated - QR code generated
• qr_scanned - QR code scanned
• tts_announcement - TTS announcement triggered
• tts_status_update - TTS status updated

🧪 Testing

API Testing

# Test the backend API
npm run test:api

Manual Testing

1. Start both servers
2. Open the frontend application
3. Use the "Backend Integration Example" component
4. Test payment creation, confirmation, and TTS

📊 Database Schema

Payments Table

CREATE TABLE payments (
  id TEXT PRIMARY KEY,
  payer_name TEXT NOT NULL,
  amount REAL NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending',
  qr_code_data TEXT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  confirmed_at DATETIME,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Payment Logs Table

CREATE TABLE payment_logs (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  payment_id TEXT NOT NULL,
  action TEXT NOT NULL,
  details TEXT,
  timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (payment_id) REFERENCES payments (id)
);

TTS Announcements Table

CREATE TABLE tts_announcements (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  payment_id TEXT NOT NULL,
  message TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending',
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  played_at DATETIME,
  FOREIGN KEY (payment_id) REFERENCES payments (id)
);

🎯 Usage Examples

Frontend Integration

import { api, PaymentSoundboxWebSocket } from '@/lib/api'

// Create a payment
const payment = await api.createPayment('John Doe', 25.50)

// Confirm payment
await api.confirmPayment(payment.id, 'John Doe', 25.50)

// WebSocket connection
const ws = new PaymentSoundboxWebSocket()
ws.onMessage((data) => {
  if (data.type === 'payment_confirmed') {
    // Handle payment confirmation
  }
})

Backend API Calls

# Create payment
curl -X POST http://localhost:3001/api/payments \
  -H "Content-Type: application/json" \
  -d '{"payerName": "John Doe", "amount": 25.50}'

# Confirm payment
curl -X POST http://localhost:3001/api/payments/PAY-123/confirm \
  -H "Content-Type: application/json" \
  -d '{"payerName": "John Doe", "amount": 25.50}'

# Test TTS
curl -X POST http://localhost:3001/api/tts/test \
  -H "Content-Type: application/json" \
  -d '{"message": "Test announcement"}'

🔧 Configuration

Environment Variables

• PORT - Backend server port (default: 3001)
• NODE_ENV - Environment (development/production)
• CORS_ORIGIN - CORS origin for frontend
• TTS_ENABLED - Enable/disable TTS functionality

Frontend Configuration

• NEXT_PUBLIC_API_URL - Backend API URL
• WebSocket URL: ws://localhost:3001

🚀 Deployment

Production Build

# Build frontend
npm run build

# Start production server
npm run start

Docker Deployment

# Backend Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY server/ ./server/
EXPOSE 3001
CMD ["npm", "run", "server"]

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📝 License

This project is licensed under the MIT License.

🆘 Support

For support and questions:

• Check the documentation
• Review the API endpoints
• Test with the provided examples
• Check server logs for errors

🔮 Future Enhancements

• Real payment gateway integration
• Advanced TTS voice selection
• Payment analytics dashboard
• Mobile app support
• Multi-language support
• Payment receipt generation
• Advanced security features
• Payment history export
• Real-time notifications
• Payment scheduling

---

Built with ❤️ for modern payment processing