BCC007 Pay - Member & Payment Management System

A production-ready member management and payment processing platform built for Brilliant Child College 2007 alumni to manage dues, events, and help-desk operations with real-time updates and secure automated flows.

---

🛠 Tech Stack

Frontend

• Framework: React Router v7 (Framework Mode)
• Styling: Tailwind CSS
• Icons: Lucide React
• Components: UI components based on shadcn/ui
• Client State: TanStack Query & React Context

Backend

• Framework: Express.js with TypeScript
• Contract: ts-rest for type-safe API communication
• Database: MongoDB via Mongoose
• Authentication: Better Auth
• Payments: Paystack API
• Background Jobs: Upstash QStash/Workflow
• Real-time: Server-Sent Events (SSE)

---

🚀 Application Flows

1. User Authentication & Onboarding

The system uses a two-tier onboarding process to ensure all members are verified and have complete profiles.

• Registration: Admins can register members. New members receive a temporary password via email (Upstash QStash).
• First Login: Members log in, verify their email, and complete their profile information.
• Onboarding Checklist:
  • Basic Info (Phone, Gender, Location, Occupation)
  • Update Profile Avatar (Cloudinary)
  • Complete Bank Details (for future payouts or transfers)
• Completion: Once all steps are completed, the isOnboarded status is updated, and the user gains full access to the dashboard.

2. Financial & Payment Flow (Paystack)

The core of the application is a secure payment processing engine for dues, event fees, and donations.

• Initialization: A member selects a payment type (e.g., Monthly Dues). The client calls initializePayment, and the server communicates with Paystack to generate a unique transaction reference and checkout URL.
• Processing: The user is redirected to Paystack's secure portal to complete the transaction.
• Verification: After payment, the user is redirected back to /dashboard/payments/verify. The server then confirms the status with Paystack's API.
• Sync & SSE: Once verified, the transaction is recorded in MongoDB. An SSE event (payment:completed) is broadcasted to all logged-in sessions to update UI stats in real-time.

3. Events & Engagement

• Event Creation: Admins create events with descriptions, dates, and optional fees.
• Engagement: Members can mark interest in events.
• Payments: If an event has a fee, members can pay directly through the integrated payment flow.

4. Help Desk & Support

• Ticketing: Members can create support tickets for technical or payment-related issues.
• Resolution: Admins manage tickets from the dashboard, assigning staff and updating status (Open -> In-Progress -> Resolved).
• Communication: Status updates trigger real-time notifications to the affected member via SSE.

5. Real-time Notifications (SSE)

The application maintains a persistent connection (/api/v1/sse/stream) to keep the dashboard alive without manual refreshes.

• Broadcasts include: payment:completed, ticket:updated, event:created, and member:created.
• These events automatically trigger TanStack Query cache invalidations, ensuring the UI always displays fresh data.

---

📁 Project Structure

├── client/                 # React Router 7 Frontend
│   ├── app/
│   │   ├── components/     # UI & Shared Components
│   │   ├── context/        # Stores & Application State
│   │   ├── features/       # Feature-specific logic (dashboard, payments, etc.)
│   │   ├── routes/         # Page components & layouts
│   │   └── lib/            # Utilities (storage, queryClient)
│   └── public/             # Static Assets
├── server/                 # Express.js Backend
│   ├── src/
│   │   ├── config/         # Environment, Auth, & DB Config
│   │   ├── contract/       # ts-rest API definitions
│   │   ├── middleware/     # Security, Rate Limiting, Auth
│   │   ├── models/         # Mongoose Schemas
│   │   ├── workflows/      # Upstash Workflow Jobs
│   │   └── routes/         # API Implementations
│   └── index.ts            # Entry Point

---

📝 Configuration & Security

• Security Headers: Managed via Helmet with custom CSP policies for Cloudinary and Paystack.
• Rate Limiting: Granular rate implementation for sensitive endpoints (Auth, Payments) using express-rate-limit.
• Validation: Strict input sanitization and typing via Zod across both client and server.

---

🔐 Environment Variables

Create a .env.development file in the server/ directory for local development, or .env.staging for staging. On Vercel, set these as Environment Variables in the project dashboard.

Server (server/.env.development)

# ── App ──
NODE_ENV=development

# ── Database (MongoDB) ──
DATABASE_URL=mongodb://localhost:27017
DATABASE_NAME=bcc007pay

# ── Authentication (Better Auth) ──
BETTER_AUTH_URL=http://localhost:4600
BETTER_AUTH_SECRET=<generate with: openssl rand -hex 32>

# ── URLs ──
CLIENT_URL=http://localhost:4500
SERVER_URL=http://localhost:4600

# ── Cloudinary (Media Uploads) ──
CLOUDINARY_CLOUD_NAME=<your-cloud-name>
CLOUDINARY_API_KEY=<your-api-key>
CLOUDINARY_SECRET_KEY=<your-secret-key>
CLOUDINARY_UPLOAD_PRESET=<your-upload-preset>

# ── Paystack (Payments) ──
PAYSTACK_SECRET_KEY=<your-secret-key>
PAYSTACK_PUBLIC_KEY=<your-public-key>

# ── Upstash (Redis + Background Jobs) ──
UPSTASH_REDIS_REST_URL=<your-redis-url>
UPSTASH_REDIS_REST_TOKEN=<your-redis-token>
QSTASH_TOKEN=<your-qstash-token>
QSTASH_URL=<your-qstash-url>

# ── Resend (Email) ──
RESEND_API_KEY=<your-resend-api-key>

# ── Sentry (Error Tracking) ──
SENTRY_DSN=<your-sentry-dsn>    # Optional

Client (client/.env)

# ── Sentry (Source Maps) ──
SENTRY_AUTH_TOKEN=<your-sentry-token>
SENTRY_ORG=<your-sentry-org>
SENTRY_PROJECT=<your-sentry-project>

# ── E2E Testing (Playwright) ──
E2E_ADMIN_EMAIL=admin@example.com
E2E_ADMIN_PASSWORD=<password>
E2E_MEMBER_EMAIL=member@example.com
E2E_MEMBER_PASSWORD=<password>

Required Services

Service	Purpose	How to Get
MongoDB	Database	MongoDB Atlas or local instance
Paystack	Payment processing	Paystack Dashboard → Settings → API Keys
Cloudinary	Image uploads	Cloudinary Console → Dashboard
Upstash	Redis cache + QStash workflows	Upstash Console → Create Redis DB + QStash
Resend	Transactional emails	Resend Dashboard → API Keys
Better Auth	Auth (uses its own keys)	Generate BETTER_AUTH_SECRET via openssl rand -hex 32
Sentry	Error monitoring (optional)	Sentry → Projects → Client Keys

---

🏗 Development & CI/CD Workflow

To ensure a high-standard, production-ready codebase, the project follows a strict branching and CI/CD strategy.

1. Branching Model

• main: The production-ready branch. Only merges from staging are allowed via Pull Requests.
• staging: The integration branch. All feature branches and bug fixes must be merged here first for testing.
• feature/* or fix/*: Temporary branches for new development or patches.

2. Branch Protection Rules

Both main and staging branches are protected to prevent accidental direct pushes and ensure quality:

• Pull Requests (PRs) Required: All changes must go through a PR. Direct pushes to main and staging are blocked.
• Status Checks: GitHub Actions must pass (Linting, Typechecking, Unit Tests, E2E Tests) before a merge is permitted.
• Code Reviews:
  • main requires at least 1 approving review from a code owner.
  • staging requires a successful PR and passing CI (no manual approval required for solo development speed).
• Admin Enforcement: These rules apply to everyone, including repository owners, to ensure a consistent workflow.

3. CI/CD Operations

• CI (GitHub Actions): Every PR to staging or main triggers an automated pipeline:
  • Server: Typechecks and Vitest unit/integration tests.
  • Client: Typechecks, Vitest unit tests, and Playwright E2E tests.
• Deployment:
  • Merges to main trigger a production deployment to Vercel for both client and server applications.

4. Contributing

When starting a new task:

1. Create a feature branch from latest staging.
2. Push changes and open a PR targeting staging.
3. Use the provided PR Template to describe your changes.
4. Once CI passes and the PR is merged, create a subsequent PR from staging to main for production release.