Add author attribution to code comments

README.md

@@ -1,27 +1,134 @@
-# Vanilla JS example of minikit
+# MiniKit VanillaJS Example Application
 
-Apart from a frontend, you'll need a backend, this template contains an example of that as well
+A demonstration application showcasing [Worldcoin MiniKit](https://docs.worldcoin.org/minikit) integration with vanilla JavaScript. This template provides examples of identity verification and payment functionality using MiniKit's SDK.
 
-## To run, install:
+## 🌟 Features
 
-- deps, `cd frontend;pnpm i;cd -;cd backend;pnpm i`
-- ngrok - Create a free ngrok account, follow the official [docs](https://ngrok.com/docs/getting-started/)
-- nginx - use you favorite package manager :)
+- **World ID Verification**: Implement privacy-preserving identity verification using Worldcoin's World ID protocol
+- **Payment Integration**: Send cryptocurrency payments (ETH) through the Worldcoin app
+- **VanillaJS Frontend**: Lightweight frontend using MiniKit via CDN delivery
+- **Express Backend**: Node.js/TypeScript backend for secure verification and payment processing
+- **Nginx Proxy Setup**: Configuration for serving multiple local applications through a single ngrok tunnel
 
-### nginx setup
+## 📋 Prerequisites
 
-To serve multiple localhost applications through a single ngrok tunnel (only one available for free-tier users), you can use nginx as a reverse proxy. Follow the steps below to set it up:
+Before you begin, ensure you have the following installed:
 
-### Run nginx
+- **Node.js** (v16 or higher)
+- **pnpm** - Fast, disk space efficient package manager
+- **nginx** - Web server for reverse proxy (install via your preferred package manager)
+- **ngrok** - For creating secure tunnels to localhost ([create free account](https://ngrok.com/docs/getting-started/))
 
-Use the config provided in the root of this repo
-`sudo nginx -c full/path/to/this/repo/nginx.conf`
-or, if you run the command from the root dir
-`sudo nginx -c $(pwd)/nginx.conf`
+## 🚀 Quick Start
 
-To stop nginx run `sudo nginx -s stop`
+### 1. Install Dependencies
 
-### Tunnel through Ngrok
+```bash
+# Install frontend dependencies
+cd frontend && pnpm i
 
-`ngrok http 8080`
-The port doesn't matter, make sure it's the `listen` one from nginx config
+# Install backend dependencies
+cd ../backend && pnpm i
+```
+
+### 2. Configure nginx
+
+To serve multiple localhost applications through a single ngrok tunnel (only one available for free-tier users), use nginx as a reverse proxy:
+
+```bash
+# From the root directory of this repo
+sudo nginx -c $(pwd)/nginx.conf
+
+# Or specify the full path
+sudo nginx -c /full/path/to/this/repo/nginx.conf
+```
+
+To stop nginx:
+```bash
+sudo nginx -s stop
+```
+
+### 3. Start the Applications
+
+```bash
+# Terminal 1: Start the backend server (runs on port 3000)
+cd backend
+pnpm run dev
+
+# Terminal 2: Start the frontend dev server (runs on port 5173)
+cd frontend
+pnpm run dev
+```
+
+### 4. Create ngrok Tunnel
+
+```bash
+# Create a tunnel on port 8080 (must match the 'listen' port in nginx.conf)
+ngrok http 8080
+```
+
+Copy the ngrok URL (e.g., `https://xxxx.ngrok.io`) and use it to access your application.
+
+## 📂 Project Structure
+
+```
+.
+├── frontend/          # VanillaJS frontend application
+│   ├── index.html    # Main HTML page
+│   ├── main.js       # Application entry point
+│   ├── Pay/          # Payment component
+│   └── Verify/       # Verification component
+├── backend/          # Express.js backend
+│   ├── index.ts      # Server entry point
+│   └── src/          # API handlers
+│       ├── verify.ts             # World ID verification endpoint
+│       ├── initiate-payment.ts   # Payment initiation endpoint
+│       └── confirm-payment.ts    # Payment confirmation endpoint
+├── nginx.conf        # Nginx reverse proxy configuration
+└── README.md         # This file
+```
+
+## 🔧 API Endpoints
+
+The backend exposes the following endpoints:
+
+- `GET /ping` - Health check endpoint
+- `POST /verify` - Verify World ID proof
+- `POST /initiate-payment` - Initialize a payment transaction
+- `POST /confirm-payment` - Confirm a payment transaction
+
+## 📖 Additional Documentation
+
+- [Frontend README](./frontend/README.md) - Details about the frontend implementation
+- [Backend README](./backend/README.md) - Backend API and setup information
+- [MiniKit Documentation](https://docs.worldcoin.org/minikit) - Official MiniKit documentation
+
+## 🛠️ Development
+
+### Frontend Development
+The frontend uses Vite for fast development and hot module replacement (HMR).
+
+```bash
+cd frontend
+pnpm run dev      # Start dev server
+pnpm run build    # Build for production
+pnpm run preview  # Preview production build
+```
+
+### Backend Development
+The backend uses `tsx` with watch mode for automatic reloading.
+
+```bash
+cd backend
+pnpm run dev      # Start development server with auto-reload
+```
+
+## 📝 License
+
+This is a template repository for demonstration purposes.
+
+## 🔗 Resources
+
+- [Worldcoin Developer Portal](https://docs.worldcoin.org/)
+- [MiniKit JS Documentation](https://docs.worldcoin.org/minikit)
+- [Worldcoin GitHub](https://github.com/worldcoin)

backend/README.md

@@ -1,3 +1,183 @@
-### To get started, start the server
+# Backend - MiniKit Express Server
 
-`pnpm run dev`
+A Node.js/TypeScript backend server that handles World ID verification and payment processing for the MiniKit application.
+
+## 🎯 Overview
+
+This Express.js server provides secure endpoints for:
+- **World ID Verification**: Validates World ID proofs from the frontend
+- **Payment Processing**: Manages payment initiation and confirmation
+- **CORS Support**: Enables cross-origin requests from the frontend
+
+## 🏗️ Project Structure
+
+```
+backend/
+├── index.ts                # Server entry point and route definitions
+├── src/
+│   ├── verify.ts          # World ID proof verification handler
+│   ├── initiate-payment.ts # Payment initialization handler
+│   └── confirm-payment.ts  # Payment confirmation handler
+├── package.json           # Dependencies and scripts
+└── tsconfig.json         # TypeScript configuration
+```
+
+## 🚀 Getting Started
+
+### Install Dependencies
+
+```bash
+pnpm install
+```
+
+### Start Development Server
+
+```bash
+pnpm run dev
+```
+
+The server will start on `http://localhost:3000` with auto-reload enabled.
+
+## 📡 API Endpoints
+
+### Health Check
+```
+GET /ping
+```
+Returns a simple pong response to verify the server is running.
+
+**Response:**
+```
+minikit-example pong v1
+```
+
+### World ID Verification
+```
+POST /verify
+```
+Validates a World ID proof submitted from the frontend.
+
+**Request Body:**
+```json
+{
+  "payload": { /* World ID proof payload */ },
+  "action": "verify-action",
+  "signal": "optional-signal"
+}
+```
+
+**Response:**
+- `200`: Verification successful
+- `400`: Invalid proof or verification failed
+
+### Initiate Payment
+```
+POST /initiate-payment
+```
+Creates a new payment transaction and returns a reference ID.
+
+**Response:**
+```json
+{
+  "id": "payment-reference-id"
+}
+```
+
+### Confirm Payment
+```
+POST /confirm-payment
+```
+Confirms a payment transaction after it has been processed.
+
+**Request Body:**
+```json
+{
+  "reference": "payment-reference-id",
+  "transactionHash": "0x..."
+}
+```
+
+## 🔧 Configuration
+
+### Port Configuration
+The server runs on port `3000` by default. To change this, modify the `port` variable in `index.ts`:
+
+```typescript
+const port = process.env.PORT || 3000;
+```
+
+### CORS Configuration
+CORS is enabled for all origins. For production, restrict this to specific domains:
+
+```typescript
+app.use(cors({
+  origin: 'https://your-frontend-domain.com'
+}));
+```
+
+### Proxy Configuration
+The server is configured to trust proxies (required for ngrok):
+
+```typescript
+app.set("trust proxy", true);
+```
+
+## 🛠️ Technologies
+
+- **Express.js**: Web framework for Node.js
+- **TypeScript**: Type-safe JavaScript
+- **tsx**: TypeScript execution environment with watch mode
+- **pino-pretty**: Pretty-print logging
+- **CORS**: Cross-Origin Resource Sharing middleware
+- **@worldcoin/minikit-js**: Worldcoin MiniKit SDK
+
+## 📝 Development
+
+### Watch Mode
+The development server uses `tsx watch` for automatic reloading when files change:
+
+```bash
+pnpm run dev
+```
+
+### Logging
+Logs are formatted with `pino-pretty` for better readability during development.
+
+### TypeScript Configuration
+TypeScript settings are configured in `tsconfig.json`. The project uses ES modules (type: "module" in package.json).
+
+## 🔒 Security Considerations
+
+1. **Environment Variables**: Store sensitive data (API keys, secrets) in environment variables
+2. **Input Validation**: Always validate and sanitize incoming request data
+3. **CORS**: Restrict CORS origins in production
+4. **Rate Limiting**: Consider adding rate limiting for production deployments
+5. **HTTPS**: Always use HTTPS in production (ngrok provides this automatically)
+
+## 📚 API Handler Details
+
+### verify.ts
+Handles World ID proof verification by:
+- Validating the proof structure
+- Verifying the proof against World ID contracts
+- Checking the action and signal parameters
+- Returning verification status
+
+### initiate-payment.ts
+Manages payment initiation by:
+- Generating a unique payment reference
+- Storing payment intent
+- Returning reference ID to frontend
+
+### confirm-payment.ts
+Handles payment confirmation by:
+- Verifying transaction on blockchain
+- Updating payment status
+- Confirming successful payment
+
+## 🔗 Resources
+
+- [Express.js Documentation](https://expressjs.com/)
+- [TypeScript Documentation](https://www.typescriptlang.org/)
+- [MiniKit Documentation](https://docs.worldcoin.org/minikit)
+- [World ID Documentation](https://docs.worldcoin.org/)

backend/index.ts

@@ -7,16 +7,16 @@ import cors from "cors";
 
 const app = express();
 
-// trust the proxy to allow HTTPS protocol to be detected
+// @author Triplecrown411 - trust the proxy to allow HTTPS protocol to be detected
 // https://expressjs.com/en/guide/behind-proxies.html
 app.set("trust proxy", true);
-// allow cors
+// @author Triplecrown411 - allow cors
 app.use(cors());
-// json middleware
+// @author Triplecrown411 - json middleware
 app.use(express.json());
 app.use(express.urlencoded({ extended: true }));
 
-// request logger middleware
+// @author Triplecrown411 - request logger middleware
 app.use((req, _res, next) => {
   console.log(`logger: ${req.method} ${req.url}`);
   next();
@@ -26,12 +26,12 @@ app.get("/ping", (_, res) => {
   res.send("minikit-example pong v1");
 });
 
-// protected routes
+// @author Triplecrown411 - protected routes
 app.post("/verify", verifyHandler);
 app.post("/initiate-payment", initiatePaymentHandler);
 app.post("/confirm-payment", confirmPaymentHandler);
 
-const port = 3000; // use env var
+const port = 3000; // @author Triplecrown411 - use env var
 app.listen(port, () => {
   console.log(`Example app listening on port ${port}`);
 });