UWFlow is one Git repository containing the frontend, Go services, Hasura schema, and deployment configuration. A single branch or PR can update the entire stack.
| Directory | Contents |
|---|---|
frontend/ |
React application, Bun lockfile, frontend Dockerfile, Vercel configuration |
flow/ |
Go API, email worker, and UW importer |
hasura/ |
Database migrations and GraphQL metadata |
nginx/ |
Production frontend and API reverse proxy |
script/, staging/ |
Build/deploy scripts and staging infrastructure |
Run make help to list every make target.
After the one-time frontend setup and backend setup, start the whole stack with:
make startThis starts the backend containers in the background, then runs the frontend
development server in the foreground at http://localhost:3000. Ctrl-C stops
only the frontend; stop the backend with make stop.
To run one half on its own, use make frontend-start or make backend-start.
Do this once per clone.
-
Install the Bun version in
frontend/.bun-version. -
From the repository root, install dependencies and the Git hooks:
make frontend-install make hooks
Rerun make frontend-install whenever frontend/bun.lock changes.
To run the frontend together with the backend, use make start (see
Running UWFlow locally). To run only the frontend:
make frontend-startThe development server runs at http://localhost:3000.
Use these while you work. None of them are required for onboarding.
| Command | What it does |
|---|---|
make frontend-check |
Lint, TypeScript, and unit tests (run before opening a PR) |
make frontend-lint |
Lint only, without changing files |
make frontend-typecheck |
TypeScript only |
make frontend-test |
Unit tests only |
make frontend-build |
Production build, without uploading Sentry source maps |
make frontend-generate |
Regenerate GraphQL types (needs the local backend running with a matching Hasura schema) |
See the frontend README for Vercel previews, and frontend/docs for GraphQL codegen, modals, pages, search, and analytics.
The backend has five components. Each runs as a separate Docker container,
managed by docker-compose.
- Postgres stores all of the data for UWFlow.
- Hasura is a GraphQL engine on top of Postgres. The frontend uses it for ordinary CRUD operations. Hasura also enforces permissions, defines relationships between tables, and manages database migrations. See the Hasura README for details and for creating migrations.
- API (
flow/api) is a Go server for operations that Hasura cannot handle alone: authentication, transcript and calendar parsing, webcal generation, and search data for frontend autocomplete. - UW Importer (
flow/importer/uw) is a scheduled job that imports courses, instructors, and term schedules from the UW API. - Email (
flow/email) watches a queue table in Postgres and sends HTML emails over Google SMTP.
In production, an Nginx reverse proxy routes /graphql to Hasura, /api to the
API, and / to the frontend.
dockerdocker-compose- Optional:
hasura-cli, for the Hasura console andmake migrate.
Package names vary across distributions. For example, Ubuntu calls docker
docker.io. The backend is developed on Linux. macOS should work. Windows is
not supported.
Do this once, and again whenever you want to reset your local database.
Warning: both setup commands below delete your local Postgres volume and replace it.
- Install the requirements.
- Copy
.env.sampleto.envin the repository root. The sample values work for local development, except:UW_API_KEY_V3: required to import course data. See how to obtain a key.POSTGRES_DUMP_PATH: only needed if you set up from a dump (option B below).POSTGRES_HOST: keeppostgreson Linux and macOS.
- Create the database using one of the options below.
make setup-contribThis creates a fresh Postgres database, applies the Hasura migrations, imports course data from the UW API, and adds dummy professors. It takes several minutes. The database has no users or reviews.
make setupThis restores the dump at POSTGRES_DUMP_PATH.
- Maintainers can use a dump of production, for example copied from the production
server with
scp, to test against the latest data. - Contributors can use the public dump instead of option A, for example when the UW API has closed registration and the import fails. It contains course data and fake professors, but no users or reviews.
Pick one:
make start # backend and frontend dev server, from your local code
make backend-start # backend only, from your local Go code
make start-public # all services, including the frontend, from the published Docker Hub imagesmake start and make backend-start run api and email with live reloading
through Air. Hasura picks up migration and metadata changes from hasura/
automatically.
The importer does not reload, because it is a scheduled job. After changing it, rebuild it and run a job:
make import-course # import courses, instructors, and schedules
make import-vacuum # run the term and course vacuum jobsStop everything with make stop.
| Command | What it does |
|---|---|
make test |
Run Go tests in the running api container |
make build-test |
Check that the Go code compiles, in the running api container |
make docker-build-test |
Dry run of the Docker Compose build |
make migrate |
Apply Hasura migrations and metadata (needs hasura-cli) |
make migrate-status |
Show Hasura migration status |
make import-profs |
Add dummy professors (already done by make setup-contrib) |
make course-renames |
Apply the course renames in hasura/course_renames.sql |
make prof-aliases |
Apply the prof aliases and merges in hasura/prof_aliases.sql |
make ps |
Show the status of all services |
make logs |
Tail logs from all services. Use logs-api, logs-hasura, logs-uw, or logs-email for one service |
You can also run Go commands directly from flow/.
While the backend runs, services listen on the ports in .env:
| Service | Default address |
|---|---|
| API | http://localhost:8081 |
| Hasura GraphQL | http://localhost:8080/v1/graphql |
| Postgres | localhost:5432 |
Contributors do not need this section. CircleCI validates every PR and publishes
images when changes merge to main.
./script/build.shbuilds all four application images. Pass service names to build a subset, for example./script/build.sh frontend. Images use theneuwflow/*names and get both a commit-SHA tag andlatest.make frontend-container-testsmoke-tests a built frontend image with Nginx and disposable mock upstreams. It needs Docker and OpenSSL.make migration-testtests the build and deploy scripts without Docker.- On the production checkout,
./script/deploy.shdeploys all services, and./script/deploy.sh frontenddeploys only the frontend. SetUWFLOW_IMAGE_TAGin.envto pin images to a published commit; otherwise Compose useslatest. Pulling images does not update the checkout's Nginx, Compose, or Hasura files. - Vercel uses
frontendas its project Root Directory, connected toUWFlow/uwflow.
See the migration and cutover runbook for the CI and Vercel handoff and for rollback.