Phase 2: Coach onboarding + contractor agreement

forgejo_admin commented

2026-03-09 17:34:15 +00:00

Owner

Lineage

plan-2026-03-08-tryout-prep → Phase 2 (Coach onboarding + contractor agreement)

Repo

forgejo_admin/basketball-api

User Story

As a coach (KJ, Madi, Mani, Abby)
I want to sign a 1099 contractor agreement and set up direct deposit
So that I'm officially onboarded and can view the player roster before tryouts

Context

Tryouts are March 13. 4 coaches need to be onboarded as 1099 independent contractors with direct deposit via Stripe Connect Express. The Coach model doesn't exist yet — needs to be created from scratch.

What already exists:

Auth: pal-e-auth with role-based access (admin, coach role exists in auth but no Coach DB model)
Stripe integration: webhook handler, payment links working
EIN available in ~/secrets for Stripe Connect platform setup

Decisions made in planning:

Coach onboarding before pay structure — get contractors signed and Stripe Connect set up now. Pay amounts settled later.
All staff are 1099 independent contractors (including owners)
Lucas's EIN for Stripe Connect for now — switch to 501(c)(3) EIN later if/when obtained
Digital acceptance: click "I agree" + timestamp + IP = legally binding
All 4 phases ship before March 13 — coach onboarding is NOT deferred

File Targets

Files the agent should modify or create:

src/basketball_api/models.py — add Coach model
alembic/versions/ — new migration for Coach table
src/basketball_api/routes/coach.py — new: onboarding flow (GET /coach/onboard → agreement page, POST → accept + Stripe Connect)
src/basketball_api/services/stripe_connect.py — new or extend existing: Stripe Connect Express account creation + onboarding link generation

Files the agent should NOT touch:

src/basketball_api/routes/register.py — that's Phase 1
src/basketball_api/services/email.py — that's Phase 3

Acceptance Criteria

Coach model exists with fields: id, tenant_id (FK), name (String), email (String), phone (String), role (String: head_coach/assistant/director), address (Text), tax_id_collected (Boolean), stripe_connect_account_id (String), contractor_agreement_signed (Boolean), contractor_agreement_signed_at (DateTime), onboarding_status (Enum: invited → agreement_signed → stripe_connected → active), created_at (DateTime)
Alembic migration creates Coach table cleanly
GET /coach/onboard returns HTML page with full contractor agreement text and "I agree" form collecting name, email, phone, address
Contractor agreement includes: independent contractor status, scope (coaching for Westside Kings & Queens), compensation TBD, at-will term, tax obligations on contractor, player/parent confidentiality
On agreement acceptance: records timestamp + IP, creates Stripe Connect Express account, generates onboarding link, redirects coach to Stripe Express onboarding
Callback endpoint handles Stripe notification when coach completes Express onboarding — updates onboarding_status to stripe_connected/active
After onboarding complete, coach can authenticate and view player roster

Test Expectations

Unit test: Coach model fields exist with correct types
Unit test: Agreement acceptance records timestamp and IP
Unit test: Stripe Connect Express account creation (mock Stripe API)
Integration test: Full onboarding flow — accept agreement → Stripe redirect → callback → status update
Run command: pytest tests/ -v

Constraints

Match existing route and model patterns in the codebase
Stripe Connect Express (not Standard or Custom) — simplest for contractors
EIN from ~/secrets/stripe/ — check for exact path/filename at runtime
Agreement page must be mobile-friendly
onboarding_status enum: invited → agreement_signed → stripe_connected → active

Checklist

PR opened
Tests pass
No unrelated changes

project-westside-basketball — project this affects
Phase 1 (registration form) runs in parallel — no dependency
Phase 3 (email blast) depends on this — coach invite email links to /coach/onboard
Coaches: KJ, Madi, Mani, Abby (target: 3 male, 1 female)

### Lineage `plan-2026-03-08-tryout-prep` → Phase 2 (Coach onboarding + contractor agreement) ### Repo `forgejo_admin/basketball-api` ### User Story As a coach (KJ, Madi, Mani, Abby) I want to sign a 1099 contractor agreement and set up direct deposit So that I'm officially onboarded and can view the player roster before tryouts ### Context Tryouts are March 13. 4 coaches need to be onboarded as 1099 independent contractors with direct deposit via Stripe Connect Express. The Coach model doesn't exist yet — needs to be created from scratch. **What already exists:** - Auth: pal-e-auth with role-based access (admin, coach role exists in auth but no Coach DB model) - Stripe integration: webhook handler, payment links working - EIN available in `~/secrets` for Stripe Connect platform setup **Decisions made in planning:** - Coach onboarding before pay structure — get contractors signed and Stripe Connect set up now. Pay amounts settled later. - All staff are 1099 independent contractors (including owners) - Lucas's EIN for Stripe Connect for now — switch to 501(c)(3) EIN later if/when obtained - Digital acceptance: click "I agree" + timestamp + IP = legally binding - All 4 phases ship before March 13 — coach onboarding is NOT deferred ### File Targets Files the agent should modify or create: - `src/basketball_api/models.py` — add Coach model - `alembic/versions/` — new migration for Coach table - `src/basketball_api/routes/coach.py` — new: onboarding flow (GET /coach/onboard → agreement page, POST → accept + Stripe Connect) - `src/basketball_api/services/stripe_connect.py` — new or extend existing: Stripe Connect Express account creation + onboarding link generation Files the agent should NOT touch: - `src/basketball_api/routes/register.py` — that's Phase 1 - `src/basketball_api/services/email.py` — that's Phase 3 ### Acceptance Criteria - [ ] Coach model exists with fields: id, tenant_id (FK), name (String), email (String), phone (String), role (String: head_coach/assistant/director), address (Text), tax_id_collected (Boolean), stripe_connect_account_id (String), contractor_agreement_signed (Boolean), contractor_agreement_signed_at (DateTime), onboarding_status (Enum: invited → agreement_signed → stripe_connected → active), created_at (DateTime) - [ ] Alembic migration creates Coach table cleanly - [ ] `GET /coach/onboard` returns HTML page with full contractor agreement text and "I agree" form collecting name, email, phone, address - [ ] Contractor agreement includes: independent contractor status, scope (coaching for Westside Kings & Queens), compensation TBD, at-will term, tax obligations on contractor, player/parent confidentiality - [ ] On agreement acceptance: records timestamp + IP, creates Stripe Connect Express account, generates onboarding link, redirects coach to Stripe Express onboarding - [ ] Callback endpoint handles Stripe notification when coach completes Express onboarding — updates onboarding_status to stripe_connected/active - [ ] After onboarding complete, coach can authenticate and view player roster ### Test Expectations - [ ] Unit test: Coach model fields exist with correct types - [ ] Unit test: Agreement acceptance records timestamp and IP - [ ] Unit test: Stripe Connect Express account creation (mock Stripe API) - [ ] Integration test: Full onboarding flow — accept agreement → Stripe redirect → callback → status update - Run command: `pytest tests/ -v` ### Constraints - Match existing route and model patterns in the codebase - Stripe Connect Express (not Standard or Custom) — simplest for contractors - EIN from `~/secrets/stripe/` — check for exact path/filename at runtime - Agreement page must be mobile-friendly - onboarding_status enum: invited → agreement_signed → stripe_connected → active ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `project-westside-basketball` — project this affects - Phase 1 (registration form) runs in parallel — no dependency - Phase 3 (email blast) depends on this — coach invite email links to /coach/onboard - Coaches: KJ, Madi, Mani, Abby (target: 3 male, 1 female)