Beest

The NestJS + SvelteKit + PostgreSQL codebase powering Beest, a hackathon in the Netherlands

The Beest codebase is what runs on https://beest.hackclub.com. That website is the You Ship We Ship platform allowing participants to sign in, create and share projects, recieve feedback and earn prizes through the shop.

This is a monorepo with two applications:

git clone https://github.com/hackclub/beest

cd beest


# Start the database
docker compose -f docker-compose.dev.yml up -d



# Backend

cd backend
npm install
cp .env.example .env     # fill in credentials
npm run migration:run
npm run start:dev         # runs on :3001


# Frontend (in a second terminal)

cd frontend
npm install
npm run dev               # runs on :5173

# Airtable
AIRTABLE_API_KEY=
AIRTABLE_BASE_ID=
AIRTABLE_TABLE_NAME=

=

# Hack Club Auth OAuth
CLIENT_ID=
CLIENT_SECRET=
REDIRECT_URI=http://localhost:5173/oauth/callback

k

# JWT & encryptiontion
JWT_SECRET=
DB_ENCRYPTION_KEY=         # 32-byte hex string for AES-256-GCM


# Hackatime OAuth
HACKATIME_CLIENT_ID=
HACKATIME_CLIENT_SECRET=
HACKATIME_REDIRECT_URI=http://localhost:5173/auth/hackatime/callback
HACKATIME_BASE_URL=https://hackatime.hackclub.com

om

# Database
DATABASE_URL=postgresql://postgres:password@localhost:5432/postgres



# Slack
SLACK_BOT_TOKEN==

BACKEND_URL=http://localhost:3001

docker compose up --build

Both backend/ and frontend/ have their own multi-stage Dockerfiles (Node 22 Alpine). Point DATABASE_URL at your PostgreSQL instance and set all backend env vars.

All endpoints live under the backend at /api. Auth-protected routes require a Bearer JWT in the Authorization header.

This repository includes a certificates feature used to generate, persist and verify participation/fulfilment certificates.

• Generation: certificates are created server-side when an order is fulfilled (idempotent per order).
• Storage: certificates are persisted in the database with a unique certificate_number (format CERT--andom-id>), recipient_name, approved_hours, award_item, and certificate_text.
• PDF: certificates are rendered server-side from HTML to PDF (Puppeteer) in landscape A4.

Key files and routes:

• Backend service: backend/src/certificates/certificate.service.ts (generation, HTML/PDF renderer, syncCertificatesForUser).
• Backend controller: backend/src/certificates/certificate.controller.ts — public verify endpoint GET /api/certificates/verify/:certificateNumber and authenticated sync POST /api/certificates/sync.
• Frontend verify page: frontend/src/routes/verify/+page.svelte and proxy frontend/src/routes/api/certificates/verify/[certificateNumber]/+server.ts (public lookup UI).
• Preview template: frontend/static/example-certificate.html (visual template used for previewing the certificate design).

How to use locally:

• Fulfil an order via the backend ShopService flow to trigger certificate generation. Generation is idempotent (re-running for the same order will not create duplicates).
• To backfill certificates for an existing user, sign in on the frontend; the site layout calls POST /api/certificates/sync to create any missing certificates for fulfilled orders.
• Public verification: open the frontend verify page and enter a certificate number, or call the backend GET /api/certificates/verify/:certificateNumber directly.

Optional: signature images

• The certificate template and generator support swapping the stylized handwritten signature text for actual signature images. Provide image URLs and I can wire them into example-certificate.html and backend/src/certificates/certificate.service.ts.

Made with <3 by by euan , give it a ⭐