Volunteerly - SENG 513

Volunteerly is a full-stack web platform that connects skilled volunteers with organizations that need specialized help. It is built as a monorepo with a Next.js client, an Express + Prisma server, and a shared package for common schemas and types.

---

Tech Stack / Tool Reference

Frontend

• Next.js 16 - https://nextjs.org/docs
• React - https://react.dev/reference/react
• Typescript - https://www.typescriptlang.org/docs/
• Tailwind CSS - https://tailwindcss.com/
• Shacdn/ui - https://www.shadcn.io/
• Leaflet - https://leafletjs.com/
• Supabase JS - https://supabase.com/docs/reference/javascript/introduction

Backend

• Node.js 20.19.0 - https://nodejs.org/en/learn/getting-started/introduction-to-nodejs
• Express.js 5.2.1 - https://expressjs.com/en/5x/api.html
• Prisma ORM 7.4.2 - https://www.prisma.io/docs/orm
• TypeScript - https://www.typescriptlang.org/
• PostgreSQL 16 - https://www.postgresql.org/docs/
• Supabase - https://supabase.com/docs
• Zod - https://zod.dev/
• Azure Document Intelligence - https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/
• Azure Communication Services - https://learn.microsoft.com/en-us/azure/communication-services/

Tooling/Infrastructure

• Node Package Manager - https://docs.npmjs.com/
• Docker - https://docs.docker.com/reference/dockerfile/
• Docker Compose - https://docs.docker.com/compose/
• Supabase CLI - https://supabase.com/docs/guides/local-development/cli/getting-started
• Make - https://www.gnu.org/software/make/
• Jest - https://jestjs.io/
• ESLint - https://eslint.org/docs/latest/
• Prettier - https://prettier.io/docs/
• Gitlab CI/CD - https://docs.gitlab.com/ci/

Monorepo Structure

The project consists of 3 packages:

• client/ - Next.js frontend
• server/ - Express Backend
• shared/ - shared Zod schemas and types used by both client and server

Each package and the repository root contain a package.json with useful development commands. Type npm run to view available commands

You can manage each package individually by adding: -w (package) to the end of a npm run command

Examples:

npm run build -w shared
npm run typecheck -w client
npm run db:setup -w server

Development Setup

The dev environment is ran using docker for a consistent cross-platform environment.

Prerequisites

1. Install necessary tools

Docker Desktop (reccomended), Docker engine (required):

• https://docs.docker.com/desktop/

• Ensure PostgreSQL client is setup, you should be able to run commands using sql

2. Verify installation

docker --version
docker compose version
make # Should print out a list of available commands
node --version
npm --version

3. Set environment variables

In repo root:

• touch .env

Place environment variables only in this file

(DO NOT COMMIT SECRETS TO REPOSITORY)

4. Install packages

From repository root: npm install

5. Run Development environment

Simplest method:

docker compose up --build
supabase start
# After supabase has initialized:
npm run db:reset -w server

This will:

1. Build and run the client and server containers
2. Start supabase containers
3. Bootstrap authenication to SQL

*** Note: it is possible to run the client and backend without docker, but not reccomended due to potential issues across development environments.

*** Note: Always remember to run npm run db:reset -w server after resetting the database, or auth will not properly bootstrap

Services

After startup the following services are available:

Client: http://localhost:3000 Server: http://localhost:4000

Migrations

The project uses Prisma Migrations.

Generate the prisma client:

• npm run prisma:generate -w server

Run Migrations

• npm run prisma:migrate -w server

*** Note: Never manually deleted a migration file unless it is an untracked change in your current working branch. If you need to make a change or revert after a commit, simply edit the schema file and rerun migrations.

Migration Conventions:

Use standard snake_case for column names through the use of the @map() attribute

For tables use @@map() and follow snake_case as well.

The following fields should be in every table that represents a tracked entity within the database schema:

createdAt DateTime @default(now()) @map("created_at")
updatedAt DateTime @updatedAt @default(now()) @map("updated_at")

Enforce id primary keys on every table with @id @default(uuid())

Define both sides of relationship in schema when referencing tables through primary keys

Supabase Auth Integration

Volunteerly uses Supabase Auth for authentication.

When a user signs up:

1. Supabase inserts a row in auth.users
2. A database triggers automatically inserts a related record into public.users, mapping them by keys while protecting the authentication data.

Supabase Local Development

a local supabase instance is used in development. From the repository root:

• supabase start

You can access the supabase dashboard locally at:

http://localhost:54323

To view your connection settings, run:

npx supabase status

Reset the local database by running:

• npm run db:reset -w server

Authentication Flow

Volunteerly uses Supabase Auth.

At a high level:

1. Supabase creates the auth user
2. a database trigger inserts a related public user record
3. after login/signup, the app routes through a session provider and redirects users to the correct dashboard based on role

API Contract

API schemas are defined in the shared/ package using Zod. This provides runtime validation and shared types between frontend and backend

After adding your schema to shared/src run:

• npm run build -w shared

Alternatively, you can run:

• npm run dev -w shared

For automatic reloading.

CSS

Use components from shacdn/ui. Styling for web application is set in /client/src/app/globals.css.

Imported components can be styled by accessing the relevant .tsx file for that component inside /client/src/components/ui

Docker

Docker Compose is used for local development. The project uses three compose files to separate shared, development and production container settings:

• docker-compose.yml - Base configuration
• docker-compose.override.yml - Development overrides
• docker-compose.prod.yml - Production overrides

For normal development, run:

docker compose up --build

To test the application in a production-like setup, run:

docker compose -f docker-compose.yml -f docker-compose.prod.yml up --build

This disables development only behaviour (hot reload, bind mounts)

***Note: docker-compose.prod.yml is intended for validation only. The actual hosted deployment uses:

• Vercel for the frontend
• Render for the backend

For local development, Docker Compose reads environment variables from the root .env file.

For local testing of production, you may optionally use a separate .env.prod file:

docker compose --env-file .env.prod -f docker-compose.yml -f docker-compose.prod.yml up --build

schema-milestone : Seeding Script Instructions

1. Prerequisites

   Ensure you have Node.js installed

   node --version

2. Clone Repository

   git clone https://csgit.ucalgary.ca/saad.abdullah1/seng513-202601-pg-40.git

3. In repo root, run npm commands

   npm install supabase

   npm install prisma

   Need to install Supabase CLI to run Supabase locally and Prisma for migrations

4. Set your environment variables

   In repo root:

   • touch .env

   • Place environment variables only in this file, use from sample or submission

5. Run Supabase Locally

   npx supabase start

   Copy the authentication key -> Secret into the .env file

   Copy the authentication key -> Publishable into the .env file

6. Run the seeding script

   npm run db:reset -w server

Workspace READMEs

See the package-level READMEs for more detail:

• client/README.md
• server/README.md
• shared/README.md

Notes

• Use npm run in the root or in a workspace to inspect all available scripts.