💸 PayFlow

PayFlow is a wallet and money-transfer backend built to practice the constraints that make financial systems genuinely harder than a typical CRUD app: state that must never go negative, every change independently auditable, and access control that has to account for more than just "logged in or not."

Every user gets a wallet with a live balance. Users can top up their balance, send money to any other registered user by email, and see a full, timestamped ledger of every transaction they've been part of. An admin role can view every user and transaction platform-wide and freeze or unfreeze accounts — and that freeze takes effect immediately, even against tokens issued before the freeze happened.

On top of the core ledger sits a Spending Insights engine: a live 7-day rolling aggregation that compares a user's current week of transfers against the previous week, computes percent change, and surfaces their top counterparty — all computed directly from the transaction collection, no external service required.

Backend: Node.js · Express.js · MongoDB Atlas · Mongoose · JWT · bcryptjs · Zod · CORS

Frontend: Next.js (App Router) · Tailwind CSS · React Context (auth state)

Tooling: Postman (manual endpoint verification) · MongoDB Atlas (managed cluster)

PayFlow/
├── backend/
│   ├── server.js                  # Entry point — connects DB, starts server
│   ├── src/
│   │   ├── app.js                 # Express app, CORS, route mounting
│   │   ├── config/db.js           # MongoDB connection
│   │   ├── models/
│   │   │   ├── user.model.js
│   │   │   └── transaction.model.js
│   │   ├── controllers/
│   │   │   ├── auth.controller.js
│   │   │   ├── wallet.controller.js
│   │   │   └── admin.controller.js
│   │   ├── middleware/
│   │   │   ├── auth.middleware.js
│   │   │   └── admin.middleware.js
│   │   ├── routes/
│   │   │   ├── auth.routes.js
│   │   │   └── admin.routes.js
│   │   └── validators/
│   │       └── auth.validator.js
│   └── package.json
│
└── frontend/
    ├── app/
    │   ├── page.js                # Landing page
    │   ├── login/page.js
    │   ├── signup/page.js
    │   ├── dashboard/page.js      # Wallet, transfers, insights, history
    │   ├── lib/
    │   │   ├── api.js             # Fetch wrapper for backend calls
    │   │   └── AuthContext.js     # Auth state (token, login, logout)
    │   ├── layout.js
    │   └── globals.css
    └── package.json

• Node.js (v18+)
• A MongoDB Atlas cluster (free tier is fine)

git clone https://github.com/deekshaasingh/PayWall.git
cd PayWall

cd backend
npm install

Create a .env file inside backend/:

MONGO_URI=your_mongodb_atlas_connection_string
JWT_SECRET=your_jwt_secret

Run it:

node server.js

You should see Database Connected Successfully! and Server is running on port 5000!

cd ../frontend
npm install

Create a .env.local file inside frontend/:

NEXT_PUBLIC_API_URL=http://localhost:5000

Run it:

npm run dev

Visit http://localhost:3000.

Note on Atlas: if you see a MongooseServerSelectionError, whitelist your current IP under Atlas → Network Access, and check your cluster hasn't auto-paused from inactivity (common on the free tier).

Promoting a user to admin is intentionally not exposed as an API endpoint — it's done by manually setting role: "admin" on a user document in MongoDB Atlas. This removes the self-escalation attack surface entirely rather than trying to secure it.

• Passwords are hashed with bcrypt (cost factor 10) — never stored or logged in plaintext
• authMiddleware re-fetches the user from MongoDB on every request rather than trusting the JWT payload — so a frozen account loses access immediately, not just after its token expires
• Admin routes are gated by a separate adminMiddleware, keeping authentication and authorization as distinct concerns
• /admin/users explicitly excludes the password field from its response, even though it's already hashed

Known limitation: the transfer endpoint updates sender and receiver balances with two independent .save() calls rather than a single atomic MongoDB session transaction. In a production system, this would be wrapped in session.startTransaction() to eliminate a theoretical partial-failure edge case. Documented here deliberately, as a known trade-off rather than an oversight.

• Admin panel frontend (backend endpoints are built and tested)
• Deployment (Render/Railway for backend, Vercel for frontend)
• Atomic transfers via MongoDB session transactions
• AI-assisted fraud/anomaly detection on transfers
• Natural-language transfer input