Monorepo Structure

A detailed look at the monorepo organization and package relationships.

Repository Layout

uwdsc-website-v3/
├── .github/                # GitHub Actions
├── apps/                   # Frontend applications
│   ├── web/                # Main website and member applications
│   ├── admin/              # Admin dashboard and CXC application/review
│   └── docs/               # Documentation site
├── packages/               # Shared packages
│   ├── ui/                 # Design system (@uwdsc/ui)
│   ├── common/             # Shared types and utils (@uwdsc/common)
│   ├── server/             # Backend
│   │   ├── db/            # @uwdsc/db - Postgres, Supabase, BaseRepository, migrations
│   │   ├── core/          # @uwdsc/core - Shared services
│   │   └── admin/         # @uwdsc/admin - Admin-only services
│   ├── eslint-config/      # ESLint configuration
│   └── typescript-config/  # TypeScript configuration
├── scripts/                # Tool scripts (migrate, ui-add, pull-secrets)
├── package.json            # Root package configuration
├── pnpm-workspace.yaml     # Workspace configuration
└── turbo.json              # Turborepo configuration

Apps

`apps/web` - Main Website

The primary UW Data Science Club website.

Purpose: Public-facing website with events, team info, and membership applications

Tech Stack:

Next.js 16 (App Router)
React 19
TypeScript
Tailwind CSS

Key Features:

Home page with events showcase
Team directory
Membership application system
Calendar integration
User authentication

Structure:

apps/web/
├── app/                 # Next.js App Router
│   ├── api/             # API routes
│   ├── (auth)/          # Auth pages (login, register, etc.)
│   ├── apply/           # Member application flow
│   ├── calendar/        # Calendar page
│   ├── passport/        # Member passport
│   ├── team/            # Team directory
│   ├── layout.tsx
│   └── page.tsx         # Home
├── components/          # React components
├── constants/           # App constants
├── contexts/           # React contexts
├── hooks/               # React hooks
├── lib/                 # Utilities, API client, services
├── providers/           # React providers
└── public/              # Static assets

`apps/admin` - Admin App

Admin dashboard and CXC (AI hackathon) application and review system.

Purpose: Admin-only features: member management, CXC applications table, review interface, superadmin dashboard and leaderboard

Tech Stack: Next.js 16, React 19, TypeScript, Tailwind, @uwdsc/ui, @uwdsc/core, @uwdsc/admin, @uwdsc/db

Key Features:

Member listing and management
CXC application submissions table and details
Review interface with scoring
Superadmin dashboard (analytics, RSVP timeline) and review leaderboard

Structure:

apps/admin/
├── app/                 # Next.js App Router
│   ├── (admin)/         # Admin dashboard, applications, review, leaderboard
│   ├── api/             # API routes
│   ├── login/           # Login page
│   └── unauthorized/    # Unauthorized page
├── components/          # React components
├── contexts/           # React contexts
├── hooks/               # React hooks
├── lib/                 # Utilities, API client, services
└── providers/           # React providers

`apps/docs` - Documentation

This documentation site.

Purpose: Developer documentation and guides

Tech Stack: Next.js 15 (Nextra-compatible), Nextra, MDX

Structure:

apps/docs/
├── pages/               # Nextra/Pages Router (MDX docs)
│   ├── architecture/
│   ├── changelog/
│   ├── guides/
│   ├── packages/
│   ├── _meta.js         # Section navigation
│   └── ...
└── public/              # Static assets

Packages

`packages/ui` - Design System

Shared UI components built with shadcn/ui.

Exports: @uwdsc/ui

Contents:

Button, Card, Input, Select
Navigation Menu, Tabs
Dialog, Dropdown, Popover
Avatar, Badge, Progress
And more shadcn components

Dependencies: Radix UI primitives, Tailwind CSS, Framer Motion, Lucide React icons

Structure:

packages/ui/
└── src/
    ├── components/      # shadcn/ui components
    ├── hooks/           # useToast, useMobile, etc.
    ├── lib/             # utils (cn, etc.)
    └── styles/          # globals.css

`packages/server/db` - Database & Supabase (`@uwdsc/db`)

Database connection, Supabase clients, and base repository.

Exports: @uwdsc/db, @uwdsc/db/connection, @uwdsc/db/supabase, @uwdsc/db/baseRepository

Contents:

Postgres connection (postgres.js, Supabase Transaction Pooler)
createSupabaseBrowserClient, createSupabaseServerClient, createSupabaseMiddlewareClient
BaseRepository abstract class (repositories extend this and use protected sql)
Migrations (db-migrate; SQL files in src/migrations/)

Structure:

packages/server/db/
└── src/
    ├── config/          # connection.ts, supabase.ts, baseRepository.ts
    └── migrations/      # db-migrate SQL and runner

Run migrations from root: pnpm migrate, pnpm migrate:down, pnpm migrate:create, etc.

`packages/server/core` - Shared Backend (`@uwdsc/core`)

Shared services and repositories used by web and admin apps.

Exports: @uwdsc/core — service classes and singletons: profileService, applicationService, teamService; AuthService, ResumeService (create per-request in app lib/services.ts via createAuthService() / createResumeService())

Contents:

AuthService, ProfileService, ApplicationService, FileService, ResumeService, TeamService
Repositories (ProfileRepository, ApplicationRepository, AuthRepository, etc.) extending BaseRepository from @uwdsc/db
Types and utilities

Structure:

packages/server/core/
└── src/
    ├── repositories/    # ProfileRepository, ApplicationRepository, etc.
    ├── services/        # Auth, Profile, Application, File, Resume, Team
    └── utils/           # Shared utilities

Dependencies: @uwdsc/db, @uwdsc/common

`packages/server/admin` - Admin Backend (`@uwdsc/admin`)

Admin-only services (e.g. profile/member management for admin dashboard).

Exports: @uwdsc/admin — e.g. profileService for member listing/updates

Used by: apps/admin API routes only

Dependencies: @uwdsc/core, @uwdsc/db, @uwdsc/common

Structure:

packages/server/admin/
└── src/
    ├── repositories/    # Admin-specific data access
    └── services/       # Admin profile/member services

`packages/eslint-config`

Shared ESLint configuration.

Exports:

@uwdsc/eslint-config/base
@uwdsc/eslint-config/next
@uwdsc/eslint-config/react-internal

Purpose: Consistent code style across all packages

`packages/typescript-config`

Shared TypeScript configuration.

Exports:

@uwdsc/typescript-config/base.json
@uwdsc/typescript-config/nextjs.json
@uwdsc/typescript-config/react-library.json

Purpose: Consistent TypeScript settings

Workspace Configuration

`pnpm-workspace.yaml`

Defines which directories are part of the workspace:

packages:
  - "apps/*"
  - "packages/*"
  - "packages/server/*"

`turbo.json`

Configures Turborepo tasks (build order, caching, env):

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": [".next/**", "!.next/cache/**"]
    },
    "dev": { "cache": false, "persistent": true },
    "lint": { "dependsOn": ["^lint"] },
    "check-types": { "dependsOn": ["^check-types"] }
  }
}

Dependency Management

Internal Dependencies

Packages reference each other using workspace protocol:

{
  "dependencies": {
    "@uwdsc/ui": "workspace:*",
    "@uwdsc/core": "workspace:*",
    "@uwdsc/db": "workspace:*"
  }
}

Shared Dependencies

Common dependencies are installed once at the root:

React, Next.js
TypeScript
Tailwind CSS
ESLint, Prettier

App-Specific Dependencies

Apps can have their own unique dependencies:

apps/web: e.g. SWR, react-feather, babel-plugin-react-compiler
apps/admin: e.g. @tanstack/react-table, sonner

Build Order

Turborepo automatically determines build order:

Config packages (eslint-config, typescript-config)
packages/common (shared types/utils)
packages/ui (design system)
packages/server/db (connection, BaseRepository, migrations)
packages/server/core (depends on db, common)
packages/server/admin (depends on core, db, common)
Apps (depend on ui, core, and optionally admin/db)

Import Paths

In Apps

// UI components
import { Button, Card } from "@uwdsc/ui";
 
// Shared backend (web and admin)
import { profileService, applicationService } from "@uwdsc/core";
import { createAuthService, createResumeService } from "@/lib/services"; // uses @uwdsc/db + @uwdsc/core
 
// Admin-only (admin app API routes)
import { profileService } from "@uwdsc/admin";
 
// Database / Supabase (when creating services)
import { createSupabaseServerClient } from "@uwdsc/db";

In Packages

// In @uwdsc/core or @uwdsc/admin
import { BaseRepository } from "@uwdsc/db/baseRepository";
import { sql } from "@uwdsc/db/connection";

Adding New Packages

1. Create Package Directory

mkdir -p packages/my-package/src
cd packages/my-package

2. Initialize package.json

{
  "name": "@uwdsc/my-package",
  "version": "0.0.1",
  "private": true,
  "main": "./src/index.ts",
  "types": "./src/index.ts"
}

3. Add to Dependencies

In consuming package/app:

{
  "dependencies": {
    "@uwdsc/my-package": "workspace:*"
  }
}

4. Install and Build

pnpm install
pnpm build

Best Practices

✅ Do

Keep packages focused and single-purpose
Use workspace protocol for internal dependencies
Follow the dependency direction (apps → packages)
Share common code in appropriate packages
Use TypeScript for type safety

❌ Don’t

Create circular dependencies
Have packages depend on apps
Duplicate code across packages
Mix different concerns in one package

Next Steps

Design System - UI component structure
API Architecture - Backend patterns

Overview Design System

Monorepo Structure

Repository Layout

Apps

apps/web - Main Website

apps/admin - Admin App

apps/docs - Documentation

Packages

packages/ui - Design System

packages/server/db - Database & Supabase (@uwdsc/db)

packages/server/core - Shared Backend (@uwdsc/core)

packages/server/admin - Admin Backend (@uwdsc/admin)

packages/eslint-config

packages/typescript-config

Workspace Configuration

pnpm-workspace.yaml

turbo.json

Dependency Management

Internal Dependencies

Shared Dependencies

App-Specific Dependencies

Build Order

Import Paths

In Apps

In Packages

Adding New Packages

1. Create Package Directory

2. Initialize package.json

3. Add to Dependencies

4. Install and Build

Best Practices

✅ Do

❌ Don’t

Next Steps

`apps/web` - Main Website

`apps/admin` - Admin App

`apps/docs` - Documentation

`packages/ui` - Design System

`packages/server/db` - Database & Supabase (`@uwdsc/db`)

`packages/server/core` - Shared Backend (`@uwdsc/core`)

`packages/server/admin` - Admin Backend (`@uwdsc/admin`)

`packages/eslint-config`

`packages/typescript-config`

`pnpm-workspace.yaml`

`turbo.json`