BidForge — Admin API (NestJS)

Trusted backend for the BidForge auction platform. Handles admin authentication, product CRUD, automatic auction closing, and push notifications — all enforced server‑side.

---

🚀 Live Demo

• API Base URL: https://bidforge-admin-api-production.up.railway.app
• Health Check: GET / → { "status": "ok" }

---

📸 Screenshots (API Testing)

Health Check	Products Endpoint	Auth Guard

Add your own Postman/Bruno screenshots inside screenshots/.

---

📋 Table of Contents

• Architecture
• Features
• Tech Stack
• Project Structure
• Setup
• Deployment
• CI/CD
• Environment Variables
• API Endpoints
• Contributing
• License

---

Architecture

This backend is part of a three‑repo system:

Customer Flutter App (Firebase client SDK)
│
▼
Firebase Project
▲
│ firebase-admin SDK (trusted)
│
┌─────────┴─────────┐
│ NestJS Backend │
│ - Auth Guard │
│ - CRUD │
│ - Cron Jobs │
│ - FCM Push │
└────────────────────┘
▲
│ HTTP (ID token)
│
React Admin Dashboard

The backend never trusts the client. Every admin request carries a Firebase ID token verified server‑side. Auctions close automatically using the server’s clock, and real push notifications are sent via FCM.

---

Features

• FirebaseAuthGuard — verifies Firebase ID tokens + custom claims (admin role)
• Products CRUD — create, read, update, publish/unpublish, delete
• Auction auto‑close — @Cron job runs every minute, finalizes winners
• Push notifications — sends real FCM messages to winners
• CORS — configured for the admin frontend
• Environment‑based config — Firebase service account JSON or file path

---

Tech Stack

• NestJS (Node.js framework)
• Firebase Admin SDK (Firestore, Auth, Messaging)
• TypeScript
• Railway (hosting)

---

Project Structure

src/
├── main.ts # Bootstrap, CORS, listen
├── app.module.ts # Root module
├── auth/
│ ├── auth.module.ts
│ └── firebase-auth.guard.ts # Guard
├── firebase/
│ ├── firebase.module.ts
│ └── firebase.service.ts # Admin SDK init
├── products/
│ ├── products.module.ts
│ ├── products.controller.ts
│ └── products.service.ts
├── auctions/
│ ├── auctions.module.ts
│ └── auctions.service.ts # Cron job
├── notifications/
│ ├── notifications.module.ts
│ ├── notifications.controller.ts
│ └── notifications.service.ts
└── ...

---

Setup

Prerequisites

• Node.js >= 18
• Firebase project with a service account key

1. Clone & install

git clone https://github.com/Sajith22/bidforge-admin-api.git
cd bidforge-admin-api
npm install

2. Environment variables

Create a .env file (never commit):

FIREBASE_SERVICE_ACCOUNT_JSON={"type":"service_account",...}
CORS_ORIGIN=http://localhost:5173

Or use a file path:

FIREBASE_SERVICE_ACCOUNT_PATH=./serviceAccountKey.json

3. Run locally

npm run start:dev

Server starts on http://localhost:3000.

Deployment

Deployed on Railway using the Dockerfile in this repo. Railway auto‑deploys on every push to main.

CI/CD

Railway connects to the GitHub repo and automatically builds and deploys on every push. No extra configuration needed.

Environment Variables

Variable	                       Description
FIREBASE_SERVICE_ACCOUNT_JSON	    Minified Firebase service account JSON (production)
FIREBASE_SERVICE_ACCOUNT_PATH	    Path to service account JSON file (local dev)
CORS_ORIGIN	                      Allowed origin (e.g., https://bidforge-admin-web.vercel.app)

API Endpoints

Method	Endpoint	Auth	Description
GET	/	No	Health check
GET	/admin-test	Admin	Test admin claim
GET	/products	Admin	List all products
POST	/products	Admin	Create product
GET	/products/:id	Admin	Get single product
PATCH	/products/:id/publish	Admin	Toggle publish
DELETE	/products/:id	Admin	Delete product
POST	/notifications/test-send	Admin	Send test push

Contributing

Follow NestJS best practices.

Add unit/e2e tests for new features.

Use meaningful commit messages.

License

MIT

Contact

GitHub: @Sajith22