Open-source awards management — from submissions to judging to winner announcement.

GitHub · Quick start · Docs · Contributing

This is a multi-tenant platform for running awards programs end to end. Create an organization, launch programs, collect entries, run multi-round judging, open public voting, and announce winners — all from one dashboard.

Built in public and designed to be self-hosted: clone the repo, point it at your own Supabase project, and run your awards on your infrastructure.

• Organizations & programs — Multi-tenant workspace with role-based access (owner, admin, program manager, judge, applicant)
• Form builder — Drag-and-drop entry forms with multi-step sections
• Categories — Nested categories and subcategories per program
• Judging workflows — Graph-based round scheduling with linear and visual editors
• Judge management — Panels, groups, category-scoped assignments, and invite links
• Public voting — Voting rounds with leaderboards and public program pages
• Payments — Paid entries via Stripe, Razorpay, or PayPal
• Email — Invites and mass email through Resend (org- or program-level)
• Audit & security — Row Level Security in Postgres, server-side authorization, audit logs

flowchart LR
  Browser["Browser (React SPA)"]
  Supabase["Supabase\nPostgres · Auth · Storage"]
  Express["Express API\nserver/"]
  Serverless["Serverless handlers\napi/"]
  Resend["Resend"]
  Payments["Stripe / Razorpay / PayPal"]

  Browser -->|"reads (RLS)"| Supabase
  Browser -->|"mutations"| Express
  Browser -->|"some routes"| Serverless
  Express --> Supabase
  Serverless --> Supabase
  Express --> Resend
  Express --> Payments

• Reads usually go directly from the browser to Supabase; Postgres RLS enforces access.
• Privileged writes (advancement, invites, judge assignment, etc.) go through the Express server, which re-checks permissions and uses the service-role key server-side only.
• A round scheduler runs inside the Express process and drives automatic round transitions.

• Node.js 20+ and npm
• A Supabase project (supabase.com or local Supabase CLI)
• (Recommended) A Resend account for transactional email
• (Optional) Redis for API caching (REDIS_URL)
• (Optional) Payment provider keys for paid entries

git clone https://github.com/Cognivo-Future-Technologies-CFT/AwardX.git
cd AwardX
npm install

npm install also installs dependencies for the Express server via a postinstall hook.

Copy the example env file and fill in your values:

cp .env.example .env

Minimum required variables:

Recommended for full functionality:

See .env.example for storage buckets and optional integrations (Sentry, Stripe, Razorpay, PayPal).

Security: Never expose SUPABASE_SERVICE_ROLE_KEY to the browser. It bypasses Row Level Security and must stay on the server only.

Apply the SQL migrations in order against your Supabase Postgres instance:

# Option A — Supabase CLI (recommended)
supabase link --project-ref YOUR_PROJECT_REF
supabase db push

# Option B — run files manually in the Supabase SQL editor
# Execute supabase/migrations/*.sql in numeric order (001 → 026)

After schema changes, regenerate TypeScript types:

npx supabase gen types typescript --project-id YOUR_PROJECT_ID \
  > services/database.types.ts

Start the frontend and API together:

npm run dev

Verify the API is healthy:

curl http://localhost:5001/api/health
# {"ok":true}

Create an account via the signup page. Supabase Auth handles sign-in (email/password and OAuth providers such as Google and GitHub when configured in your Supabase project).

/
├── components/          # React UI — marketing pages and dashboard
├── server/              # Express API (Node 20+, port 5001)
├── api/                 # Vercel serverless route handlers
├── supabase/migrations/ # Versioned PostgreSQL migrations (RLS-aware)
├── services/            # Frontend data layer (Supabase client, API helpers)
├── lib/                 # Shared utilities
├── hooks/               # React hooks
├── tests/               # Vitest unit & integration tests
├── docs/                # Architecture and feature notes
└── public/              # Static assets

The platform splits cleanly across three deploy targets:

1. Frontend — npm run build, then host dist/ on any static host (Vercel, Netlify, Cloudflare Pages).
2. Serverless handlers — The api/ folder is picked up automatically on Vercel (vercel.json at the repo root).
3. Express server — Host server/ on Fly.io, Render, Railway, or any Node-friendly platform. Set PORT and all server-side env vars.

Production checklist

• Apply all migrations to your production Supabase project.
• Set VITE_BACKEND_URL to your public Express API URL (leave empty in local dev).
• Keep SUPABASE_SERVICE_ROLE_KEY, RESEND_API_KEY, and payment secrets on the server only.
• Configure Supabase Auth redirect URLs for your production domain.

In-app documentation lives at /docs when the dev server is running. Additional notes are in the docs/ folder, including:

• docs/SCHEDULE_ROUNDS_ARCHITECTURE.md — Round scheduling and advancement
• docs/MOBILE_APP_FEATURES.md — Mobile-oriented feature notes

# Unit + integration (Vitest)
npm test

# Targeted suites
npx vitest run tests/unit/scheduleRounds
npx vitest run tests/integration/scheduleRounds

# End-to-end (Playwright)
npm run test:e2e

Contributions are welcome. The project is built in public — issues, bug reports, and pull requests help make it better for everyone running awards programs.

1. Fork the repository and create a branch from main.
2. Set up a local environment following Quick start.
3. Make your change — keep diffs focused; match existing code style and conventions.
4. Run checks — npm run typecheck and npm test before opening a PR.
5. Open a pull request with a clear description of what changed and why.

For larger changes (new round types, schema changes, payment flows), open an issue first so we can align on approach.

The platform supports a wide range of program types — design awards, hackathons, academic admissions, fellowships, abstract submissions, and more. See workflow_readmes/ for workflow-specific notes.

This project is open source under the GNU Affero General Public License v3.0 (AGPL-3.0).

If you modify this software and run it as a network service (for example, a hosted SaaS instance), AGPL-3.0 requires you to make the corresponding source code of your modified version available to users who interact with it over the network.

Clone the repo. Run your awards.