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

Enable the repo's git hooks once per clone:

git config core.hooksPath .githooks

This runs make format in frontend/ before each commit that touches it, so formatting matches what Frontend CI checks.

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.