apportal

The Generate application portal — applications, reviews, and the hiring pipeline.

It has two parts:

• backend/ — Go API (Fiber + Huma) backed by Supabase Postgres.
• frontend/ — Next.js app (App Router) using Supabase auth.

For the domain model and the full application → review → interview → selection pipeline, see info.md.

Prerequisites

• Go 1.25+ (backend)
• Node.js 20+ and npm (frontend)
• A Supabase project (Postgres + auth)
• Optionally Docker to run the backend in a container

Backend

The Go backend connects to Supabase Postgres and can run directly on your machine or in Docker.

Environment Variables

Copy backend/.env.example to backend/.env and set:

• PORT — defaults to 8080
• DATABASE_URL — Supabase Session Pooler URL for make run
• DATABASE_URL_DOCKER — same Supabase Session Pooler URL for make docker-up

Run

From backend/:

make run

Run with Hot Reload

For development, make dev watches .go files and automatically rebuilds and restarts the server on save. It uses air (configured in backend/.air.toml) and installs it on first run if it isn't already present.

From backend/:

make dev

Run with Docker

From backend/:

make docker-up

Local Database

The Supabase project (config, migrations, seed) lives in backend/internal/supabase/. Running it locally requires Docker and the Supabase CLI.

From backend/:

supabase start --workdir internal   # start Postgres, Studio, Auth, Storage, etc.
supabase stop --workdir internal    # tear down

supabase start prints connection details, including:

• Database: postgresql://postgres:postgres@127.0.0.1:54322/postgres
• Studio (DB browser): http://127.0.0.1:54323

Point the backend at it by setting DATABASE_URL in backend/.env to the local database URL above instead of the hosted Supabase Session Pooler URL. Note that Supabase auth still requires SUPABASE_URL to point at a real project — logging in works against that, but any user without a matching row in the local users table will fail requests that look up the current actor.

Copying Prod Data Locally

A fresh local database starts empty (aside from seed.sql, if present) — no users, applications, or cycles. If you need real-shaped data to test against (e.g. to reproduce a bug, or to exercise an existing account's roles), you can copy data from the hosted project into your local one.

This isn't a maintained script, just a manual recipe — treat DATABASE_URL_DOCKER in backend/.env as the source (it already holds the hosted Supabase Session Pooler URL) and the local supabase_db_internal Docker container as the destination. Run pg_dump/psql inside that container rather than with your host's client — the local Postgres image is on a specific major version (currently 17), and pg_dump refuses to dump from a server newer than itself:

# from backend/, with the local stack already running (supabase start)
export PROD_URL=$(grep '^DATABASE_URL_DOCKER=' .env | cut -d'=' -f2-)
docker exec supabase_db_internal pg_dump "$PROD_URL" --data-only --schema=public -f /tmp/prod_data.sql
docker exec supabase_db_internal psql -U postgres -d postgres -v ON_ERROR_STOP=1 -f /tmp/prod_data.sql

This dumps every public schema table's data (not auth.* — Supabase auth is untouched) and restores it in one transaction-safe pass, so foreign key ordering across tables is handled automatically. Since this reads real user data from production, don't run it against a database or machine you wouldn't want that data sitting on.

Testing Migrations

supabase migration new <name>          # scaffold a new migration file, from backend/
supabase db reset --workdir internal   # wipe and replay all migrations from scratch

supabase db reset replays every file in backend/internal/supabase/migrations/ against a fresh database — the way to confirm a new migration actually applies cleanly (not just that it worked once against a database that already had earlier state) before merging.

Health Endpoints

• GET /healthz — liveness check for the app process
• GET /readyz — readiness check that pings Supabase Postgres
• GET /docs — Scalar API docs (OpenAPI at /openapi.json)

Useful Commands

From backend/:

• make dev — run with hot reload (rebuilds on file save)
• make fmt — format Go code and supported docs
• make fmt-check — check formatting without changing files
• make lint — run go vet and golangci-lint (config in backend/.golangci.yml)
• make test — run Go tests
• make build — build the backend binary
• make openapi — write the OpenAPI spec to backend/api/openapi.yaml (source for frontend codegen)
• make docker-down — stop the Docker Compose stack

Frontend

The Next.js frontend talks to the Go backend and uses Supabase for auth.

Environment Variables

Copy frontend/.env.example to frontend/.env and set:

• NEXT_PUBLIC_API_URL — backend base URL (defaults to http://localhost:8080)
• NEXT_PUBLIC_SUPABASE_URL — your Supabase project URL
• NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY — your Supabase publishable (anon) key

Run

From frontend/:

npm install
npm run dev    # start the dev server at http://localhost:3000

Useful Commands

From frontend/:

• npm run dev — start the dev server
• npm run build — production build
• npm run start — serve the production build
• npm run lint — run ESLint
• npm run format:check — check formatting with Prettier
• npm test — run unit tests (Vitest)
• npm run generate:api — regenerate the typed API client from the OpenAPI spec

The frontend's src/generated/ API client is generated from the backend's OpenAPI spec with Orval. After changing the backend API, run make openapi (backend) then npm run generate:api (frontend). See frontend/README.md for details.

Continuous Integration

GitHub Actions run on every pull request to main:

• Backend CI — gofmt, go vet, golangci-lint, go test, go build
• Frontend CI — lint, type-check, format, test, build

See .github/ for the workflows, Dependabot config, and PR template.