Rice Carpool

Rice Carpool is a ridesharing platform built for the Rice University community. It connects students to coordinate shared travel, making it simple to organize and join rides between Rice, Houston airports, and surrounding areas.

---

Prerequisites

Ensure you have the following installed before getting started:

• Go
• Node.js
• Docker Desktop

Note

Request the shared Google OAuth development credentials from the leads before starting local configuration.

---

Getting Started

1. Environment Configuration

1. Start Docker Desktop.

2. Create a local .env file from .env.example:

   # macOS or Linux
   cp .env.example .env

   # Windows PowerShell
   Copy-Item .env.example .env

3. Add the supplied Google OAuth values to your .env file:

   • SUPABASE_AUTH_EXTERNAL_GOOGLE_CLIENT_ID
   • SUPABASE_AUTH_EXTERNAL_GOOGLE_CLIENT_SECRET

Warning

Do not commit .env to version control.

2. Installation & Running

Run the following commands from the repository root:

# First time setup: checks tools and installs dependencies
npm run setup

# Start local database, backend, and frontend
npm run dev

Press Ctrl+C to stop local services.

Port & Service Overview

Service	Port(s)	Description
Frontend	3000	Next.js application (http://localhost:3000)
Backend	8080	Go Connect RPC server
Supabase / Database	54321, 54322	Local PostgreSQL instance

Note

• npm run setup starts Supabase briefly to validate the environment, then stops it.
• npm run dev keeps all data localized within your local Docker environment.

---

Finding Your Code

Workspace Structure

Path	Purpose
proto/carpool/v1/	API Protocol Buffer messages and request validation schemas
backend/internal/rpc/	Parse requests, invoke application services, and construct RPC responses
backend/internal/app/	Business rules, authorization, database transactions, and contact privacy
backend/internal/db/postgres/	Convert application records to and from sqlc database calls
backend/internal/db/queries/	SQL query sources; assigned queries contain headers to fill
supabase/migrations/	Database schema migrations
frontend/src/	Pre-built frontend client

---

Backend Rules

Important

Follow these guidelines strictly when writing backend logic:

1. Caller Verification: ListRides, GetRide, and ListLocations allow a missing bearer token. A supplied invalid token is rejected. Every other RPC requires rpc.actorFromContext. Request IDs select target entities; they do not establish caller identity.
2. Transaction Integrity: Begin every storage operation via app.Database.BeginTx. Repositories created from that transaction share a single Serializable snapshot. Defer rollback and build an authorized mutation result before committing.
3. Contact Privacy: Enforce privacy rules using app.projectUser and app.projectRides. Guest ride responses include trip facts and occupied_seats, but no owner, riders, or notes. Signed-in users see contacts only when permitted. Do not expose raw stored contact information in RPC responses.
4. Layer Separation:
   • RPC layer: Parsing, service invocation, error mapping, and protobuf conversion.
   • App layer (app/): Business logic and domain rules.
   • DB layer (db/postgres/): sqlc data conversion.
5. Code Generation: Edit .proto and .sql source files, then regenerate code. Do not manually edit generated files in backend/internal/gen/, backend/internal/db/sqlc/, or frontend/src/gen/.

Public browsing contract

The assigned backend operations start as stubs. Their implementations must follow these rules:

• Visitors can list locations and active rides without signing in. Discovery includes full rides and excludes departures more than one hour in the past.
• A visitor can open a ride only while it qualifies for discovery. Cancelled and older rides return NotFound to visitors; signed-in users can still open their ride history.
• Public ride results include the route, departure time, capacity, status, and occupied seats (including the driver). They omit the owner, riders, and notes. Signed-in results retain the existing contact privacy rules.
• Discovery and ride detail pages are public. Profile, ride history, creation, editing, and ride actions require sign-in and a completed profile. After sign-in and onboarding, the frontend returns users to their intended page.

---

Testing & Code Generation

Commands Quick Reference

Backend Development (run from backend/)

go build ./...    # Compile backend packages
go test ./...     # Run backend test suite
sqlc generate     # Generate Go code from SQL queries
sqlc diff         # Verify SQL query changes against database schema

Code Generation Tools

• Protobuf: Run buf generate in proto/.
• Frontend: Run npm run generate in frontend/.

Root Convenience Scripts

npm run db:start   # Start local Supabase database
npm run db:stop    # Stop Supabase database
npm run db:reset   # Reset local Supabase database
npm run backend    # Run Go backend individually
npm run frontend   # Run Next.js frontend individually

Testing Guidelines

• Database Integration Tests: Use backend/internal/testutil.SetupTestDB. It boots a disposable PostgreSQL container when Docker is available or uses an explicitly set TEST_DATABASE_URL. It ignores standard DATABASE_URL.
• CI Pipeline: Operation test checks are visible in CI (initially non-blocking to allow incremental merges). Build and code generation checks must pass.
• Frontend Checks: From frontend/, run npm test, npm run lint, npx tsc --noEmit, and npm run build. Install the browser once with npx playwright install chromium, then run npm run test:e2e for mocked public-browsing flows.

---

Contributors

Built by RiceApps Studio :>

• Andrew Chu
• Angel J Guerrero
• Calvin Wong
• Claire Li
• Dara Odukoya
• Eason Tang
• Emily Zheng
• Katherine Han
• Joya Roy
• Liya Ferede
• Marianna Argeiti
• Megan Cung
• Melody Cui
• Yiyi Sun
• Zimo Wang