DRAP: Draft Ranking Automated Processor

Welcome to DRAP: the Draft Ranking Automated Processor for the University of the Philippines Diliman - Department of Computer Science's yearly draft of research lab assignments. In a nutshell, this web application automates the mechanics of the draft:

1. All participating students register for the draft by providing their full name, email, student number, and lab rankings (ordered by preference) to the draft administrators.
2. When a draft is created, the active labs' global quotas are captured as per-draft initial quota snapshots.
3. The regular draft process begins. For each round in the draft:
   1. Draft administrators notify (typically via email) the lab heads about all of the students that have chosen their respective research lab as the first choice.
   2. Each lab selects a subset (i.e., possibly none, some, or all) of these first-choice students to accept them into the lab. After this point, the selected students are considered to be "drafted" and are thus no longer part of the next rounds.
   3. The next round begins when all of the labs have submitted their preferences. This time around, the second-choice preferences of the remaining students are evaluated (and so on).
4. Should there be students remaining by the end of the regular draft process, the lottery round begins.
5. Before the randomization stage, draft administrators first negotiate with participating labs (that have remaining slots) to check if any of the labs would like to accept some of the remaining students immediately.
6. During lottery, administrators adjust per-draft lottery quota snapshots to match remaining students exactly.
7. After manual negotiation and intervention, the remaining students are shuffled and assigned to participating labs in a round-robin fashion using the draft's lottery snapshots.
8. The draft concludes when all registered participants have been assigned to a lab.

Development

flowchart TD
    subgraph External
        direction LR
        User[Browser]
        Google[Google OAuth]
    end

    subgraph Production
        SvelteKit[DRAP:3000]

        Drizzle[DrizzleGateway:4983]

        subgraph database [database]
            Postgres[(PostgreSQL:5432)]
        end

        subgraph durability [durability]
            direction LR
            Inngest[Inngest:8288]
            SQLite[(SQLite)]
        end

        subgraph queue [queue]
            Redis[(Redis:6379)]
        end

        subgraph telemetry [telemetry]
            O2[OpenObserve:5080]
        end
    end

    User <--> SvelteKit
    Google <-->|OAuth| SvelteKit
    SvelteKit <--> Postgres
    SvelteKit <--> Inngest
    SvelteKit -.->|OpenTelemetry| O2
    Inngest <--> Redis
    Inngest <--> SQLite
    Drizzle <--> Postgres

Server Environment Variables

At runtime, the server requires the following environment variables to be present.

[!IMPORTANT] The OAuth redirect URI is computed as ${ORIGIN}/dashboard/oauth/callback.

The following variables are optional in development, but highly recommended in the production environment for OpenTelemetry integration. The standard environment variables are supported, such as (but not limited to):

[!NOTE] The "recommended" values are only applicable to the development environment with OpenObserve running in the background. See the compose.yaml for more details on the OpenObserve configuration.

Setting up the Codebase

# Install dependencies.
pnpm install

# Check formatting.
pnpm fmt

# Apply formatting auto-fix.
pnpm fmt:fix

Database Commands

# Generate Drizzle migrations.
pnpm db:generate

# Apply migrations.
pnpm db:migrate

# Open Drizzle Studio UI.
pnpm db:studio

[!IMPORTANT] You must run pnpm db:migrate on a fresh database in order to initialize the tables.

Linting the Codebase

# Check linting rules.
pnpm lint:eslint
pnpm lint:svelte

# Perform all lints in parallel.
pnpm lint

Docker Compose Files

The project uses layered Docker Compose files for different environments.

flowchart TD
    subgraph Base
        base[compose.yaml]
    end

    subgraph Development
        dev[compose.dev.yaml]
    end

    subgraph Production
        ci[compose.ci.yaml]
        prod[compose.prod.yaml]
        app[compose.app.yaml]
    end

    base --> dev
    base --> ci --> prod --> app

[!NOTE] Docker BuildKit is required to build the local services used during development. In most platforms, Docker Desktop bundles the core Docker Engine with Docker BuildKit. For others (e.g., Arch Linux), a separate docker-buildx-like package must be installed.

This requirement is due to the fact that the custom PostgreSQL image uses the TARGETARCH build argument, which is typically automatically populated by Docker BuildKit.

Running the Development Server

# Run dev services (compose.yaml + compose.dev.yaml):
# postgres, inngest (dev mode), o2
pnpm docker:dev

# Run the Vite dev server for SvelteKit.
pnpm dev

Running the Production Server

# Build the main web application (SvelteKit).
pnpm build

# Run the Vite preview server for SvelteKit.
pnpm preview

# Alternatively, run the Node.js script directly.
node --env-file=.env build/index.js

# Or, spin up CI services (compose.yaml + compose.ci.yaml):
# postgres, inngest (prod mode), redis
pnpm docker:ci

# Or, spin up production internal services (+ compose.prod.yaml):
# CI services + o2, drizzle-gateway
pnpm docker:prod

# Or, spin up full production environment (+ compose.app.yaml):
# prod services + app
pnpm docker:app

Local Telemetry with OpenObserve

To enable full observability in local development:

1. Start the local services (including OpenObserve):

   pnpm docker:dev
   

2. Export the OTEL environment variables before running the dev server:

   export OTEL_EXPORTER_OTLP_ENDPOINT='http://localhost:5080/api/default'
   export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Basic%20YWRtaW5AZXhhbXBsZS5jb206cGFzc3dvcmQ%3D'
   export OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf'
   pnpm dev
   

3. View traces and logs at http://localhost:5080.

Running the End-to-End Tests with Playwright

The Playwright configuration runs pnpm preview on port 4173 in production mode by default. A single end-to-end test features a single full draft round.

# Ensure development-only services are spun up. We _can_ use the production setup,
# but that requires a little bit more configuration. This is done in CI, but not
# necessary for local development.
pnpm docker:dev

# Build first (required by playwright.config.js webServer command).
pnpm build

# Load only .env:
source ./scripts/test-playwright.sh

source ./scripts/test-playwright.sh development
source ./scripts/test-playwright.sh production
source ./scripts/test-playwright.sh staging

# Load only .env:
nu ./scripts/test-playwright.nu

# Load .env + .env.<environment> + .env.<environment>.local:
nu ./scripts/test-playwright.nu development
nu ./scripts/test-playwright.nu production

Acknowledgements

The DRAP project, licensed under the GNU Affero General Public License v3, was originally developed by Sebastian Luis S. Ortiz, Victor Edwin E. Reyes, and Ehren A. Castillo as a service project under the UP Center for Student Innovations. The DRAP logo and banner were originally designed and created by Angelica Julianne A. Raborar.