Skip to content

Getting Started with Perfxcel

This guide covers first-time setup for local development across all three Perfxcel repositories.

Prerequisites

  • Node.js 24.x
  • A Supabase project with the perfxcel schema configured
  • Access to the DotEvolve private npm registry (for @dotevolve/error-utils, @dotevolve/ui-kit)

Repositories

Repository Purpose URL pattern
perfxcel-app Public-facing React SPA (course catalog) perfxcel.com
perfxcel-admin Internal admin SPA (DotEvolve staff only) admin.perfxcel.com
perfxcel-api Express REST API (Supabase backend) api.perfxcel.com

1 — Clone and Install

# API
git clone [email protected]:DotEvolve/perfxcel-api.git
cd perfxcel-api && npm install

# Public App
git clone [email protected]:DotEvolve/perfxcel-app.git
cd perfxcel-app && npm install

# Admin
git clone [email protected]:DotEvolve/perfxcel-admin.git
cd perfxcel-admin && npm install

2 — Environment Variables

perfxcel-api

Copy .env.example to .env.dev.local and populate:

SUPABASE_URL=https://<project>.supabase.co
SUPABASE_SERVICE_ROLE_KEY=<service-role-key>
SENTRY_DSN=
VITE_PERFXCEL_TURNSTILE_SECRET_KEY=<turnstile-secret>
VITE_PERFXCEL_TURNSTILE_HOSTNAMES=localhost,perfxcel.com
PORT=8000
NODE_ENV=development

perfxcel-app

VITE_API_URL=http://localhost:8000/api/v1
VITE_SUPABASE_URL=https://<project>.supabase.co
VITE_SUPABASE_ANON_KEY=<anon-key>

perfxcel-admin

VITE_SUPABASE_URL=https://<project>.supabase.co
VITE_SUPABASE_ANON_KEY=<anon-key>
VITE_API_GATEWAY_URL=http://localhost:8000

3 — Start Development Servers

Run each in a separate terminal:

# API (port 8000)
cd perfxcel-api && npm run dev

# Public site (port 5173)
cd perfxcel-app && npm run dev

# Admin (port 5174)
cd perfxcel-admin && npm run dev

4 — Database Schema

The API uses the perfxcel schema in Supabase. Ensure your Supabase project has the following tables set up:

  • courses — core course records with taxonomy associations
  • course_categories, course_cities, course_associations — many-to-many join tables
  • interests — learner interest submissions
  • enrollments — confirmed enrollments
  • enquiries — inbound contact enquiries
  • training_plan_requests — bulk training plan submissions
  • audit_logs — platform action log
  • taxonomy_items — shared taxonomy values (categories, cities, delivery modes, associations)

5 — Running Tests

# API
cd perfxcel-api && npm test

# Public site
cd perfxcel-app && npm test

# Admin
cd perfxcel-admin && npm test

6 — Building for Production

# API
cd perfxcel-api && npm run build

# Public site
cd perfxcel-app && npm run build

# Admin
cd perfxcel-admin && npm run build

Both frontend apps are deployed to Cloudflare Pages. The API is containerised via Dockerfile and deployed to OCI.