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. 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).
3. Should there be students remaining by the end of the regular draft process, the lottery round begins.
4. 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.
5. After manual negotiation and intervention, the remaining students are shuffled and assigned to participating labs in a round-robin fashion.
6. The draft concludes when all registered participants have been assigned to a lab.

Development

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

    subgraph Production
        SvelteKit[DRAP :3000]
        Inngest[Inngest :8288]
        Postgres[(PostgreSQL :5432)]
        Redis[(Redis :6379)]
        SQLite[(SQLite)]
        O2[OpenObserve :5080]
        Drizzle[Drizzle Gateway :4983]
    end

    User --> SvelteKit
    SvelteKit --> Google
    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

Linting the Codebase

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

# Perform all lints in parallel.
pnpm lint

Running the Development Server

# Run all database and queue services in the background.
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, just use Docker for everything.
pnpm docker:prod

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.

[!WARNING] The OTEL_* environment variables must be set in the shell before running pnpm dev or pnpm preview. They cannot be loaded from .env files because the OpenTelemetry instrumentation initializes before SvelteKit processes environment files.

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.