Golf Fundraiser Pro

Golf Scramble Made Easy — A complete tournament management platform for non-profit fundraising events.

Built in six feature phases, all delivered; work since has continued past them (schema migrations run to Phase19). This is the monorepo housing all applications and shared packages.

---

Architecture Overview

golf-fundraiser-pro/              ← Turborepo monorepo root
  apps/
    api/       → ASP.NET Core .NET 10 — REST API (port 5000)
    admin/     → Expo Router web      — Organizer dashboard (port 8081)
    mobile/    → Expo SDK 58          — iOS/Android scoring app
    web/       → Next.js 16           — Public leaderboard + landing page (port 3000)
  packages/
    ui/          → Shared React Native components (mobile + admin)
    shared-types/→ TypeScript DTOs + Zod schemas (API contracts)
    theme/       → 5-token color system + WCAG validation
  infra/
    docker-compose.yml  → PostgreSQL/PostGIS, Redis, pgAdmin
    nginx.conf          → Local reverse proxy (port 8080)
    init-scripts/       → DB initialization SQL
  .github/
    workflows/          → ci, deploy-api, deploy-admin, eas-build
                          (web deploys via Vercel's own GitHub integration —
                           there is no deploy-web workflow)

---

Technology Stack

Layer	Technology	Notes
Backend API	ASP.NET Core Web API (.NET 10)	C# 14, EF Core, controller-based
Database	PostgreSQL 16 + PostGIS 3.4	PostGIS required for GPS features
Cache	Redis 7	Leaderboard cache + SignalR backplane
Admin Dashboard	Expo Router web	Shares UI components with mobile
Public Web	Next.js 16 App Router	SSR, Vercel, JSON-LD structured data
Mobile App	React Native + Expo SDK 58	New Architecture, EAS Build
Real-Time	ASP.NET SignalR	Phase 3
Payments	Stripe	Phase 4
Email	SendGrid	100/day free tier
Auth	ASP.NET Identity + JWT	15-min access tokens

---

Prerequisites

• Node.js 24.3+ and npm 10+ (enforced by engines in the root package.json)
• .NET 10 SDK — download
• Docker Desktop — for PostgreSQL, Redis, pgAdmin
• EAS CLI — npm install -g eas-cli (for mobile builds; the Expo CLI itself ships with the expo dependency and is run via npx expo)

---

First-Time Setup

1. Clone and install

git clone https://github.com/your-org/golf-fundraiser-pro.git
cd golf-fundraiser-pro

# Install all workspace dependencies in one command
npm install

2. Configure environment

# Copy the template — never commit .env.local
cp .env.example .env.local

# Edit .env.local and fill in:
#   JWT_SECRET          → openssl rand -hex 64
#   JWT_REFRESH_SECRET  → openssl rand -hex 64  (different value)
#   SENDGRID_API_KEY    → from https://app.sendgrid.com
#   (Stripe/Mapbox keys optional until their respective phases)

3. Start the database stack

# Start PostgreSQL (PostGIS), Redis, and pgAdmin
cd infra && docker compose up -d

# Verify all three are healthy
docker compose ps

# Expected output:
#   gfp-postgres   running (healthy)
#   gfp-redis      running (healthy)
#   gfp-pgadmin    running (healthy)

pgAdmin is available at http://localhost:5050

• Email: [email protected]
• Password: admin
• The golf_fundraiser database connection is pre-configured.

4. Database migrations

In Development the API applies pending EF Core migrations automatically at startup, so step 5 below is usually all you need. Run them by hand only if you want the schema in place before the API boots:

cd apps/api
dotnet ef database update

# Verify PostGIS is enabled in pgAdmin or psql:
#   SELECT PostGIS_Version();

Outside Development this is off by default — migrations belong in the deploy step, so a bad schema never silently reaches a running service. Single-container hosts can opt in with GFP_MIGRATE_ON_STARTUP=true.

5. Start all development servers

Open four terminals:

Terminal 1 — API:

cd apps/api
dotnet run
# API available at http://localhost:5000
# Swagger UI at http://localhost:5000/swagger

Terminal 2 — Admin Dashboard:

cd apps/admin
npm run dev
# Admin at http://localhost:8081

Terminal 3 — Public Web:

cd apps/web
npm run dev
# Web at http://localhost:3000

Terminal 4 — Mobile (optional):

cd apps/mobile
npm run dev
# Metro on port 8200. Open it in a development build (expo-dev-client) —
# Expo Go can't load the app's native modules (Stripe, etc.)

Or start all JavaScript apps at once from the root:

npm run dev
# Turborepo starts admin + web + mobile in parallel
# (API still needs its own terminal — it's .NET, not JS)

---

Monorepo Commands

All commands run from the repo root:

npm run build          # Build all workspaces (packages before apps)
npm run dev            # Start all JS dev servers in parallel
npm run lint           # ESLint across all TypeScript workspaces
npm run type-check     # tsc --noEmit across all TypeScript workspaces
npm run test           # Run tests in all workspaces
npm run check-updates  # Outdated deps + watchlist version-drift check (72h install cooldown)
npm run audit:prod     # Production dependency audit gate — the same one CI runs
npm run e2e            # Clean-build end-to-end harness (e2e:fast skips the clean build)
npm run db:backup      # Dump the local database (db:restore loads a dump)
npm run clean          # Delete all build artifacts + node_modules

---

Working with Shared Packages

The three packages in packages/ are used by importing their scoped names:

// In apps/admin, apps/mobile, or apps/web:
import { ECO_GREEN_DEFAULT, buildCSSVars, validateContrast } from '@gfp/theme'
import type { EventDTO, TeamDTO, LeaderboardEntryDTO }        from '@gfp/shared-types'
import { ScoreCard, LeaderboardRow, ThemeProvider, useTheme } from '@gfp/ui'

This is the beginning of the README. Read the rest at the original. Read the full README ↗