KROGiving — Architecture¶

src/
├── admin/
│   ├── admin-auth/         — Admin authentication, JWT, OTP login
│   ├── admin-campaign/     — Campaign review, approval/rejection, messages
│   ├── admin-donation/     — Donation management, CSV export
│   ├── admin-log/          — Admin action audit logs, withdrawal cap logs
│   ├── admin-payout/       — Payout approval with TOTP 2FA
│   ├── admin-permissions/  — Permission definitions and enforcement
│   ├── admin-settings/     — Platform settings (withdrawal caps, rates)
│   └── admin-user/         — User management by admins
├── campaign/               — Campaign CRUD, public listing, slug management
├── comment/                — Campaign comments
├── currency/               — Exchange rates, currency conversion
├── donation/               — Donation initialization and verification
├── fee/                    — Platform fee calculation
├── file-upload/            — DO Spaces file management
├── global-settings/        — Platform-wide configurable settings
├── notification/
│   ├── email/              — SendGrid / MailerSend email notifications
│   └── sms/                — Termii / Telnyx SMS notifications
├── otp/                    — OTP generation and Redis-backed validation
├── payment/                — Paystack payment orchestration
├── paystack/               — Paystack API client
├── profile/                — User profiles
├── scheduler/              — Cron job definitions
├── seed/                   — Database seeders
└── withdrawal/             — Withdrawal processing

Donor opens campaign page (krogiving-frontend)
  → GET /v1/campaigns/:slug — fetch campaign details
  → POST /v1/donations/initialize — initialize Paystack transaction
  → react-paystack opens Paystack checkout modal
  → Paystack processes payment
  → Paystack sends webhook → POST /v1/paystack/webhook
  → Backend verifies webhook signature
  → Donation marked completed in PostgreSQL
  → Campaign raised amount updated
  → Donor receives email confirmation (SendGrid)

Creator logs in → JWT token
  → POST /v1/campaigns — create campaign (draft)
  → POST /v1/file-upload — upload images to DO Spaces
  → Cloudinary upload widget — upload video directly from browser
  → PUT /v1/campaigns/:id — update campaign details
  → POST /v1/campaigns/:id/submit — submit for admin review
  → Admin receives real-time Socket.IO notification (giv-admin-new)
  → Admin reviews in giv-admin-new dashboard
  → PATCH /v1/admin/campaigns/:id/status (approve/reject)
  → Creator notified via email/SMS
  → Campaign published

Campaign organizer requests withdrawal
  → POST /v1/withdrawal — submit request
  → Admin views payout queue in giv-admin-new
  → Admin initiates 2FA → POST /v1/admin/payouts/two-factor/initialize
  → Admin enters TOTP code → POST /v1/admin/payouts/approve
  → Backend triggers Paystack transfer to organizer's bank account
  → Status updated to completed
  → Organizer notified via email

Admin enters email
  → POST /v1/otp/send — OTP sent via email/SMS
  → Admin enters OTP
  → POST /v1/admin/auth/sign-in — returns JWT
  → GET /v1/admin/auth/permissions — permissions fetched and stored
  → JWT stored in Zustand; all subsequent requests use Bearer token
  → On 401: Axios interceptor attempts token refresh