KDOps — KD Squares Operations Platform

Internal finance and operations hub for KD Squares Ltd, Nigeria.
Manages payments, payroll, expenses, fleet, compliance, HR, and more — backed by Supabase and processed through Paystack.

---

Stack

Layer	Technology
Frontend	React 18 + TypeScript + Vite
Styling	Tailwind CSS + shadcn/ui
Backend / DB	Supabase (PostgreSQL + RLS + Edge Functions)
Auth	Supabase Auth (email/password)
Payments	Paystack (transfers API via Edge Functions)
Error monitoring	Sentry (optional, free tier)
Hosting	Vercel

---

Local Development

Prerequisites

• Node.js ≥ 18
• A Supabase project (free tier is fine for dev)
• A Paystack account (test keys for dev)

Setup

git clone https://github.com/king-iyene/kd-ops-hub.git
cd kd-ops-hub
npm install
cp .env.example .env.local
# Fill in .env.local — see table below
npm run dev

The dev server starts at http://localhost:5173.

---

Environment Variables

Create .env.local (never commit this file):

Variable	Required	Description
VITE_SUPABASE_URL	✅	Your Supabase project URL (https://xxx.supabase.co)
VITE_SUPABASE_ANON_KEY	✅	Supabase anon/public key
VITE_PAYSTACK_PUBLIC_KEY	✅	Paystack public key — use pk_test_ for dev, pk_live_ in prod
VITE_SENTRY_DSN	optional	Sentry DSN — leave blank to disable error reporting

Production: Set these in Vercel → Project → Settings → Environment Variables.
Sentry is a no-op when VITE_SENTRY_DSN is unset — the app works fine without it.

---

Deployment

The app deploys automatically to Vercel on push to main.

# Manual deploy (if needed)
npx vercel --prod

Security headers (CSP, HSTS, X-Frame-Options, etc.) are defined in vercel.json.

Supabase Backend (Migrations & Edge Functions)

SQL migrations (supabase/migrations/) and Edge Functions (supabase/functions/) auto-deploy via GitHub Actions on push to main:

Workflow	File	Trigger
Deploy Supabase Migrations	.github/workflows/deploy-supabase-migrations.yml	supabase/migrations/** changes on main
Deploy Edge Functions	.github/workflows/deploy-edge-functions.yml	supabase/functions/** changes on main

Required GitHub Secrets (repo → Settings → Secrets and variables → Actions):

Secret	Description
SUPABASE_ACCESS_TOKEN	Personal Access Token from supabase.com/dashboard/account/tokens
SUPABASE_PROJECT_REF	Production project ref (the slug in the project URL)
SUPABASE_DB_PASSWORD	Database password (Project Settings → Database)

Important: Each migration file must have a unique 14-digit timestamp prefix. Duplicate timestamps will cause supabase db push to fail. All migrations should be idempotent (CREATE TABLE IF NOT EXISTS, DROP POLICY IF EXISTS before CREATE POLICY, etc.).

Paystack API Access (IP Whitelisting + Proxy)

Paystack enforces IP whitelisting on the KD Squares account following a security incident. Supabase Edge Functions have no static outbound IP, so all Paystack API calls route through a dedicated Fly.io proxy (kdops-paystack-proxy) that provides a stable, whitelisted IPv4 address.

• Proxy URL: https://kdops-paystack-proxy.fly.dev
• Proxy code: paystack-proxy/index.js
• Proxy-aware fetch wrapper: supabase/functions/_shared/paystack-fetch.ts
• Deploy workflow: .github/workflows/deploy-paystack-proxy.yml

Do not disable Paystack's IP whitelist to work around failures — fix the proxy chain instead. See docs/paystack-proxy-setup.md for full setup, architecture, and troubleshooting.

---

Project Structure

src/
├── components/        # Shared UI components
│   ├── ui/            # shadcn/ui primitives
│   ├── ui-kit/        # KDOps-specific composites (TableSkeleton, ResponsiveDialog, …)
│   ├── AppLayout.tsx  # Root layout with sidebar, header, command palette
│   ├── AppSidebar.tsx # Role-aware navigation sidebar
│   └── ErrorBoundary.tsx  # React error boundary with Sentry forwarding
├── hooks/             # Custom React hooks (useDebounce, useTimeOfDay, …)
├── lib/               # Utilities and service clients
│   ├── supabase.ts    # Supabase client
│   ├── paystack.ts    # Paystack helpers + generateKdopsRef()
│   ├── audit.ts       # Audit log writer
│   ├── format.ts      # formatNaira, formatDate, …
│   └── db-errors.ts   # Friendly Supabase error messages
├── pages/             # Route-level page components
├── store/             # Zustand stores (authStore, viewAsStore)
└── main.tsx           # App entry — Sentry init, global error hooks
supabase/
├── functions/
│   ├── _shared/       # Shared helpers (paystack-fetch.ts proxy wrapper, etc.)
│   └── */index.ts     # Individual edge functions
└── migrations/        # SQL migration files
paystack-proxy/
└── index.js           # Fly.io proxy for Paystack IP whitelisting
vercel.json            # Vercel config + security headers

---

Role System

Role	Access
super_admin	Full access, can impersonate other roles via "View As"
admin	Full operational access
finance	Payments, payroll, expenses, reports
operations	Fleet, contractors, tasks
field_staff	Own expense claims, leave requests, tasks

Roles are stored in profiles.role and enforced via Supabase RLS policies.
Super admins can switch view via the View As banner to test any role's experience.

---

Key Conventions

Payment References

Every Paystack transfer initiated from this platform uses the kdops_ prefix:

kdops_{first 20 chars of UUID without dashes}

Generated by generateKdopsRef(id) in src/lib/paystack.ts. Search for kdops_ in the Paystack dashboard to identify all platform-originated transfers.

Dual Approval

Payment batches above the configured threshold require two approvers. The approved_by field stores the final approver; the audit log captures the full approval chain.

Audit Log

Every significant action (payment initiation, approval, rejection, role change, etc.) writes a row to the audit_logs table via logAudit() in src/lib/audit.ts.

---

Available Scripts

npm run dev        # Start dev server
npm run build      # Production build
npm run preview    # Preview production build locally
npx tsc --noEmit   # Type-check without building
npm audit          # Check for dependency vulnerabilities

---

Troubleshooting

Blank screen / auth loop: Check that VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY are set correctly.

Payments not processing / "Your IP address is not allowed": The Paystack proxy chain is likely broken. See docs/paystack-proxy-setup.md for the full troubleshooting checklist. The most common cause is a mismatch between the proxy's actual outbound IP and the IP whitelisted on Paystack — visit https://kdops-paystack-proxy.fly.dev/diag/ip to check.

Payments not processing (other): Ensure Paystack Edge Functions are deployed to Supabase and VITE_PAYSTACK_PUBLIC_KEY matches the key the Edge Functions use on the server side.

Transactions view missing columns: Run the latest migrations in supabase/migrations/ — particularly 20260622000000_transactions_view_remove_transfers.sql.

Console warning [KDOps] Paystack test key in production: The app detected pk_test_ in a non-localhost environment. Update VITE_PAYSTACK_PUBLIC_KEY to your live key in Vercel environment variables.