Madison Ultimate App

A web application to track signup progress for Madison Middle School Ultimate Frisbee players.

Getting Started

Prerequisites

• Node.js 24 (Active LTS; see .nvmrc)
• npm

Local Development

1. Clone the repository

   git clone <repository-url>
   cd madison-ultimate
   

2. Install dependencies

   npm install
   

3. Set up Google API access (see Google API Setup below)

4. Start the development server

   npm run dev
   

   Next.js will print the URL (e.g. http://localhost:3000). Run this in a terminal in the foreground (not as a background task). When you’re done, stop the server with Ctrl+C in that terminal. The dev server shuts down cleanly when it receives SIGINT (Ctrl+C), so the port is freed for the next run. If the server was started in the background (e.g. by an IDE), it may not receive a signal when you “stop” elsewhere—use the IDE’s Stop button for that task so the process is terminated.

5. Open your browser Navigate to the URL Next.js printed (typically http://localhost:3000).

Available Scripts

• npm run dev - Start development server (with hot reload). Stop with Ctrl+C in the same terminal for a clean shutdown.
• npm run build - Build the application for production
• npm run start - Start production server
• npm run lint - Run ESLint for code quality checks

Documentation

• PROJECT REQUIREMENTS.md - Original business requirements (historical; Stages 1-2 were superseded, see below)
• CONTEXT.md - Current domain language: player identity, Final Forms join, photos (start here for current architecture)
• Stage 3 PLAN.md - Player Portal implementation plan (historical; its login/identity model was superseded, see docs/adr/0001-player-identity-model.md)
• DESIGN.md - Technical architecture, data mapping, and implementation details
• AGENTS.md - Agent and developer guidelines, commit rules, and commands

Project Structure

madison-ultimate/
├── src/
│   ├── app/                    # Next.js app router pages
│   │   └── api/                # API routes for data processing
│   ├── components/             # Reusable UI components
│   ├── lib/                    # Utilities and API integrations
│   └── styles/                 # Global styles
├── tmp/                        # Cached data files (development)
├── public/                     # Static assets
└── *.md                        # Documentation files

Tech Stack

• Framework: Next.js 16 with App Router (React 19)
• Language: TypeScript
• Styling: Tailwind CSS 4
• Deployment: Vercel (https://madisonultimate.org)
• Data Sources: Google Sheets API, Google Drive API, Buttondown (RSS for team updates; optional API for newsletter status)

Development Workflow

This project uses conventional commits with emojis for fun! Please format your commit messages as:

type(scope): description with emojis

Examples:
feat: add player signup status table ⚽
fix: resolve data matching issue
docs: update setup instructions 📖

Current Features

• /signup: webapp-native season signup (player identity lookup/creation, profile form, Final Forms status, Buttondown newsletter, photo upload) — the primary family-facing entry point each season.
• /player/[playerId]: a Progressive Web App (PWA) player portal where students and families can view player info and status, mark availability for practices and games, and access season info and team news.

See CONTEXT.md for the current domain model and docs/adr/ for the identity/signup architecture decisions.

Double headers — multiple events on the same calendar day

The portal supports more than one game on the same calendar date (multiple events on a given calendar day; e.g. a double-header). Games are ordered from Game Info top to bottom: the first row for a date is game 1, the second row with the same date is game 2, and so on.

• Availability columns in the Game Availability sheet use M/D Availability, M/D Note, and M/D Activation Status for the first game that day, and M/D Availability (Game 2), M/D Note (Game 2), M/D Activation Status (Game 2) for the second (and (Game 3) if needed). The player app matches columns using that naming; duplicate headers like two columns both called 5/9 Availability are not supported.
• Coach spreadsheet: Run Build Game Availability in the team Google Sheet (madison-ultimate-admin Coach Sheet Apps Script) so those headers exist for each game row.
• Season setup: Naming, extra optional fields, and subtitles are documented in SEASON_SETUP.md (see Extra game fields for optional columns that also use the (Game 2) pattern).

Future ideas (player portal)

• Coach notes and links: Game coach notes are rendered as plain text today, so long URLs can dominate the card. A planned improvement is to render hyperlinks (auto-link detected URLs, optional labeled-link syntax, sanitization). See DESIGN.md → Data Sources for Player Portal → Game coach notes (plain text today; future: hyperlinks).

Google API Setup

This application requires access to Google Sheets and Google Drive to fetch player signup data. Follow these steps to set up API access:

1. Create Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Note your project ID for reference

2. Enable Required APIs

1. In the Google Cloud Console, go to "APIs & Services" > "Library"
2. Search for and enable:
   • Google Sheets API
   • Google Drive API

3. Create Service Account

1. Go to "APIs & Services" > "Credentials"
2. Click "Create Credentials" > "Service Account"
3. Fill in the service account details:
   • Name: madison-ultimate-service
   • Description: Service account for Madison Ultimate app data access
4. Click "Create and Continue"
5. Skip role assignment (we'll grant access directly to resources)
6. Click "Done"

4. Generate Service Account Key

1. Click on the newly created service account
2. Go to the "Keys" tab
3. Click "Add Key" > "Create new key"
4. Select "JSON" format
5. Download the JSON key file
6. Rename it to .google-service-account.json
7. Place it in the root of your project directory

5. Grant Access to Data Sources

You must share each Google resource with the service account email (found in the JSON key file):

For Google Sheets:

1. Open the Additional Questionnaire sheet
2. Click "Share" button
3. Add the service account email (e.g., [email protected])
4. Set permission to "Viewer"
5. Uncheck "Notify people" since it's a service account

For Google Drive Folders:

1. Open SPS Final Forms folder
2. Right-click folder > "Share"
3. Add the service account email with "Viewer" permission
4. Repeat for Team Mailing List folder

For Roster Sheet (Stage 2):

1. Open the Team Roster sheet
2. Click "Share" button
3. Add the service account email
4. Set permission to "Editor" (required for roster building functionality)
5. Uncheck "Notify people" since it's a service account

6. Configure Environment Variables

1. Copy .env.example to .env.local:

   cp .env.example .env.local
   

2. Update .env.local with your configuration:

   # Google API Configuration
   GOOGLE_SERVICE_ACCOUNT_KEY_FILE=./.google-service-account.json
   
   # Data Source IDs
   ADDITIONAL_QUESTIONNAIRE_SHEET_ID=1f_PPULjdg-5q2Gi0cXvWvGz1RbwYmUtADChLqwsHuNs
   SPS_FINAL_FORMS_FOLDER_ID=1SnWCxDIn3FxJCvd1JcWyoeoOMscEsQcW
   TEAM_MAILING_LIST_FOLDER_ID=1pAeQMEqiA9QdK9G5yRXsqgbNVzEU7R1E
   # Single workbook for roster and all related tabs (Roster, Practice Info, Game Info, Practice/Game Availability)
   ROSTER_SHEET_ID=1kV3Y_GST_Y-X9PZFXu9yFkCzGWvhk9f7G24Y8QNuayU
   

7. Security Notes

• The .google-service-account.json file contains sensitive credentials
• It's automatically ignored by git (listed in .gitignore)
• Never commit this file to version control
• For production deployment, use secure environment variable storage

Authentication Setup

This application uses dual authentication for different Google APIs:

• Service Account: For Google Sheets and Drive APIs
• Buttondown: Public RSS for "Recent Team Updates"; optional API key for newsletter status on the player page

For complete authentication setup instructions, see AUTHENTICATION_SETUP.md. For a checklist of what to set or decide each season (roster sheet, portal labels, Additional Info Form visibility, signup birth-year window, etc.), see SEASON_SETUP.md.

Deployment (Vercel)

Required Environment Variables

Set these in Vercel Dashboard → Project → Settings → Environment Variables:

# Service Account
GOOGLE_SERVICE_ACCOUNT_KEY=<full-json-content-as-string>

# Optional: Buttondown API key (subscriber write) for newsletter status and Join / Leave
# BUTTONDOWN_API_KEY=<your-buttondown-api-key>

# Resource IDs
ROSTER_SHEET_ID=<sheet-id>
SPS_FINAL_FORMS_FOLDER_ID=<folder-id>
ADMIN_SECRET=<long-random-string>   # Basic Auth password for /admin and /api/admin
TEAM_MAILING_LIST_FOLDER_ID=<folder-id>
ADDITIONAL_QUESTIONNAIRE_SHEET_ID=<sheet-id>

Continuous Deployment (GitHub → Vercel)

The Vercel project is connected to the BigLep/madison-ultimate GitHub repository. Every push to main automatically triggers a production deployment — no manual steps required.

To set this up on a new Vercel project: Project → Settings → Git → Connect Git Repository → select the repo → set Production Branch to main.

Manual Deployment

If you need to deploy manually (e.g. without a GitHub push), use the Vercel CLI:

vercel --prod

First-Time Setup Steps

1. Complete authentication setup following AUTHENTICATION_SETUP.md

2. Update OAuth redirect URI in Google Cloud Console:

   • Add production domain: https://madisonultimate.org/api/auth/callback

3. Set environment variables in Vercel dashboard

4. Connect GitHub repository for auto-deploys (see above)

5. Test:

   curl https://madisonultimate.org/api/team-updates