Developer Quickstart

EPICS Teambuilder — Developer Quickstart

Overview

Teambuilder is a web-based administrative platform for the EPICS program at UT Dallas. It automates student-to-project team assignments, manages project and partner records, integrates with Discord and GitHub, and provides demographic data visualization.

Tech Stack

• Frontend: Vue 3, Nuxt 3, PrimeVue, Tailwind CSS
• Backend: Nuxt server routes (Nitro)
• Database: SQLite via Prisma ORM
• Authentication: Better Auth — magic link login, UTD email restricted
• Email: Gmail SMTP via Nodemailer
• Package Manager: pnpm — do not use npm or yarn
• Deployment: Docker + Docker Compose

Users and Roles

There are two roles in the system:

Admin

• Full access to all pages
• Can approve, deny, and remove users from the /admin/users page
• Can promote/demote other users to admin

User

• Access to all pages except /admin/users
• Must be whitelisted by an admin before they can log in

Prerequisites

Before setting up locally, make sure you have:

• Node.js v20+
• pnpm — install with npm install -g pnpm
• Git
• A @utdallas.edu email address

Local Setup

1. Clone the repository

git clone https://github.com/UTDallasEPICS/Teambuilder.git
cd Teambuilder
git checkout stage

2. Install dependencies

pnpm install

3. Set up environment variables

Get the .env file from a current team member — it is not committed to the repo for security reasons. Place it in the root of the project.

The .env file must contain the following variables:

# Database
PRISMA_DB_URL="file:./prisma/dev.db"
DATABASE_URL="file:./prisma/dev.db"

# Discord Bot
TOKEN=
GUILD_ID=
BOT_ID=

# GitHub Integration
GITHUB_TOKEN=

# Authentication (Better Auth)
BETTER_AUTH_SECRET=
BETTER_AUTH_URL="http://localhost:3000"

# Email (Gmail SMTP)
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="465"
SMTP_USER=
SMTP_PASS=
SMTP_FROM=

⚠️ Make sure PRISMA_DB_URL uses file:./prisma/dev.db for local development. The Docker/production version uses file:/app/prisma/dev.db.

⚠️ BETTER_AUTH_URL must match the URL you are running the app on. For local dev this is http://localhost:3000. For the stage server it is https://teambuilder-stage.npts.tech.

4. Set up the database

Run migrations and seed the database:

npx prisma migrate dev

This will apply all migrations and run prisma/seed.ts, which creates the initial admin accounts and fake seed data for development.

To verify the database is set up correctly:

npx prisma studio

Open http://localhost:5555 and check that the User table has the seeded admin accounts.

5. Start the development server

pnpm dev

The app will be available at http://localhost:3000.

Authentication

The app uses magic link login restricted to @utdallas.edu email addresses.

Login flow:

1. Go to http://localhost:3000/login
2. Enter your @utdallas.edu email
3. Click "Send Magic Link"
4. Check your inbox and click the link
5. If your account is not yet whitelisted, you will see a "pending approval" screen
6. An admin must approve your account at /admin/users before you can access the app

First time setup: The seed file pre-creates admin accounts for the core team. If your email is not in the seed, ask an admin to approve you after your first login attempt.

⚠️ During local development, magic link emails can only be sent to the email address associated with the Gmail SMTP account in .env. Ask a team member if you need a link sent manually.

Admin User Management

Admins can manage users at /admin/users. This page shows:

• Pending — users who have clicked a magic link but have not been approved yet
• Active — whitelisted users with access to the app
• Removed — users who have been denied or removed

From this page admins can approve, deny, remove, restore, promote to admin, or demote from admin.

Database Migrations

When you make changes to prisma/schema.prisma, run:

npx prisma migrate dev --name describe_your_change

This generates a migration file and applies it to your local database. Commit the migration file to the repo — it will be applied to the live database automatically on the next deploy via entrypoint.sh.

To reset your local database completely (wipes all data, reruns migrations and seed):

npx prisma migrate reset

⚠️ Never run prisma migrate reset on the production server.

Docker (Local)

To run the app locally using Docker:

docker compose up --build

The app will be available at http://localhost:3000. The SQLite database is persisted in a Docker volume called db_data.

⚠️ When running in Docker, PRISMA_DB_URL must be file:/app/prisma/dev.db.

Deployment

The stage site is at https://teambuilder-stage.npts.tech. Deployment is handled by the server team. To deploy new changes:

1. Merge your branch into stage
2. The server team pulls the latest stage branch and restarts the Docker container
3. On restart, entrypoint.sh automatically runs prisma migrate deploy and prisma db seed

Project Structure

├── pages/              # Nuxt pages (frontend routes)
│   ├── login.vue       # Login page
│   ├── admin/
│   │   └── users.vue   # Admin user management
│   └── ...
├── server/
│   ├── api/            # Backend API routes
│   ├── middleware/     # Server middleware (auth, Prisma client)
│   ├── lib/
│   │   └── auth.ts     # Better Auth configuration
│   └── integrations/   # Discord and GitHub bots
├── middleware/
│   └── auth.global.ts  # Frontend route guard
├── composables/
│   └── useAuthState.ts # Auth state management
├── prisma/
│   ├── schema.prisma   # Database schema
│   ├── seed.ts         # Database seed file
│   └── migrations/     # Migration history
├── components/         # Reusable Vue components
├── algorithms/         # Team generation algorithms
└── docker-compose.yml  # Docker configuration

Known Issues

• The Discord bot may fail to connect with a 503 error during Discord outages — this is expected and does not affect the rest of the app
• Magic link emails during local development only deliver to the Gmail account owner's email due to SMTP restrictions