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
        HAProxy[HAProxy:80/443]
        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

        subgraph storage [storage]
            RustFS[RustFS:9000/9001]
        end
    end

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

Environment Variables

Development and production do not use the same environment-variable surface. The tables below split host-run app processes such as pnpm dev, pnpm preview, and node --env-file=.env build/index.js from the full production compose stack started by pnpm docker:prod:app.

[!IMPORTANT] The OAuth redirect URI is computed as ${ORIGIN}/dashboard/oauth/callback. In the production compose stack, ORIGIN and PUBLIC_ORIGIN are both derived from SCHEME and HOST. When SCHEME=https, HAProxy terminates TLS on port 443, redirects port 80 to HTTPS, and emits HSTS on HTTPS responses.

Setting up the Codebase

# Install dependencies.
pnpm install

# Generate the AES-256-GCM encryption key used for sensitive OAuth tokens.
# Save this key to the `DRAP_ENCRYPTION_KEY` environment variable in `.env`.
pnpm random:bytes -- 32

# Other useful examples:
# Save this key to the `S3_ACCESS_KEY` environment variable.
pnpm random:bytes -- 24

# Save this key to the `S3_SECRET_KEY` environment variable.
pnpm random:bytes -- 48

The generic helper script accepts a single positional <bytes> argument and prints a Base64URL-encoded random value. It is implemented in src/scripts/generate-random-bytes.js.

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.

Code Quality Enforcement

# Check formatting.
pnpm fmt

# Apply formatting auto-fix.
pnpm fmt:fix

# 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 Continuous Integration
        ci[compose.dev.ci.yaml]
    end

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

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

[!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, rustfs
pnpm docker:dev

# Bootstrap the RustFS bucket after the stack is healthy.
# Only needs to be done once per stack.
pnpm docker:dev:setup:bucket

# 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 production internal services (compose.yaml + compose.prod.yaml):
# postgres (prod), inngest (prod mode), redis, o2, rustfs, drizzle-gateway
pnpm docker:prod

# Bootstrap the RustFS bucket after the stack is healthy.
# Should be run once per redeployment.
pnpm docker:prod:setup:bucket

# Or, spin up full production environment (+ compose.prod.app.yaml):
# prod services + HAProxy ingress + app
# SCHEME=http uses port 80 only
pnpm docker:prod:app

# Or, add the TLS ingress override:
# requires repo-root ./certificate.pem when SCHEME=https
# symlink is acceptable
pnpm docker:prod:app:tls

The production HAProxy ingress uses a coarse path allowlist for the public site surface (/, /_app/, /history, /privacy, /dashboard, and root static files). Any other unmatched path is returned as an empty 404 while rate-limited requests are returned as an empty 429. Empty responses are preferred to conserve egress bandwidth. When the TLS override is enabled with SCHEME=https, HAProxy terminates TLS on port 443, redirects valid host traffic from port 80 to HTTPS, and emits Strict-Transport-Security on HTTPS responses.

Local Telemetry with OpenObserve

To enable full observability in local development:

1. Start the local services (including OpenObserve):

   pnpm docker:dev
   

2. Export the OTLP endpoint and headers before running the dev server. Trace export uses OTLP over HTTP automatically:

   export OTEL_EXPORTER_OTLP_ENDPOINT='http://localhost:5080/api/default'
   export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Basic%20YWRtaW5AZXhhbXBsZS5jb206cGFzc3dvcmQ%3D'
   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.
pnpm docker:dev

In CI, use pnpm docker:dev:ci so inngest dev can reach pnpm preview on port 4173.

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

# Load only `.env` + `.env.local`
source ./scripts/test-playwright.sh

# Include `.env.development` + `.env.development.local`
source ./scripts/test-playwright.sh development

# Include `.env.production` + `.env.production.local`
source ./scripts/test-playwright.sh production

# Load `.env` + `.env.local`
nu ./scripts/test-playwright.nu

# Include `.env.development` + `.env.development.local`
nu ./scripts/test-playwright.nu development

# Include `.env.production` + `.env.production.local`
nu ./scripts/test-playwright.nu production

[!CAUTION] In Inngest SDK v4, local development is no longer inferred automatically. Set INNGEST_DEV=http://localhost:8288 only for host-run app processes that should talk to the local Inngest dev server, such as pnpm preview during Playwright/CI and optional host-run local Inngest testing. The Docker --sdk-url values such as http://host.docker.internal:5173/api/inngest and http://host.docker.internal:4173/api/inngest still point the Inngest dev server back to the app's handler.

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.