project-page active Westside Basketball
project-groupme-westside updated 2026-03-28

Vision

Integrate GroupMe as the real-time communication layer for Westside Kings & Queens. Parents and players get auto-invited to their team's group chat when they sign their contract. Marcus and coaches manage day-to-day comms through GroupMe natively. Platform operators manage groups, membership, and messaging via MCP tools.

User Stories

Role Key Story Success Metric
Admin (Marcus) story:GM-1 As admin, I want players auto-added to their team's GroupMe when they sign their contract, so I don't manage membership manually Welcome email with GroupMe share link sent on contract signing (via outbox pattern)
Admin (Marcus) story:GM-2 As admin, I want to send announcements to team groups, so important info reaches everyone instantly Announcements go to each team group individually
Coach story:GM-4 As coach, I want my team's parents and players in a GroupMe group, so I can communicate practice changes instantly One group per team, coach is admin, all rostered families are members
Platform (Lucas/Betty Sue) story:GM-5 As platform operator, I want to create and manage GroupMe groups via MCP tools, so group setup is automated and tracked in the database MCP tools for create_group, add_member, remove_member, send_message, list_members — all name-based resolution
Platform (Lucas/Betty Sue) story:GM-6 As platform operator, I want GroupMe group IDs stored per team in the database, so the system knows where to invite parents teams.groupme_group_id + groupme_share_url populated for all teams

Plan

All 3 original tickets DONE. Incident-fix (name-based resolution) merged 2026-03-25. PreToolUse hook pending (claude-custom#160). Work tracked on board-westside-basketball.

Board

Uses board-westside-basketball — same project, shared kanban.

Status

  • GroupMe account: Created (Lucas Draney, draneylucas@gmail.com, MFA enabled)
  • API token: Verified working, stored in ~/secrets/groupme/credentials.env
  • Groups: 11 total (9 team groups + 1 staff + 1 stakeholders). Marcus is member on all, needs admin promotion in app.
  • SDK: DONE — groupme-sdk v0.1.0 merged, published to Forgejo PyPI.
  • DB migration + outbox + email: DONE — basketball-api PR #158 merged, deployed.
  • MCP: DONE — groupme-mcp v0.2.0 with name-based resolution (PR #4). PreToolUse approval hook DEPLOYED (claude-custom PR #163 merged 2026-03-25). All GroupMe write operations require explicit user approval.
  • Deploy: Live. Migration applied. Share URLs stored in DB for all 9 teams.
  • ArgoCD: Auto-sync disabled for basketball-api due to bug (pal-e-services #28).

Milestones

2026-03-24: All 3 tickets shipped. 9 team groups + 1 staff group live. SDK + MCP + outbox pattern deployed.

2026-03-25: Incident — contract status sent to Coaches & Staff group instead of Stakeholders. Name-based resolution merged (groupme-mcp PR #4). PreToolUse hook scoped (claude-custom#160).

Architecture

GroupMe integration documented in Westside Basketball architecture notes (updated 2026-03-24):

  1. Domain Model — Team.groupme_group_id + groupme_share_url
  2. Data Flow — Contract signing → outbox → welcome email with share link → parent self-joins
  3. Deployment — groupme-sdk as library, GroupMe API as external service

Key decisions:

  • SDK + MCP pattern (no FastAPI wrapper)
  • MCP tools resolve groups by name, not raw ID — live API lookup on every call, no caching (incident-driven decision 2026-03-25)
  • Parents self-join via share link (not API member-add by phone)
  • Outbox pattern: contract signing writes event to DB, worker processes async
  • Admin endpoint POST /api/admin/process-outbox for cron + testing
  • No announcements group — announcements go to each team group individually
  • GroupMe API is source of truth for membership (no local replication)

Repos

Repo Platform Role Status
groupme-sdk Forgejo Python SDK wrapping GroupMe REST API v0.1.0 merged + published
groupme-mcp Forgejo MCP server for agent-driven group management v0.2.0 — name-based resolution on all tools. Configured in ~/.mcp.json.
basketball-api Forgejo Outbox + email + reconciliation script PR #158 merged + deployed

Groups

Note: The MCP resolves groups by name via live GroupMe API. These IDs are reference only — never hardcode them in tool calls.

Group Name ID Share URL Members
WKQ Stakeholders 113996175 (private — no share link) 2 (Lucas + Marcus)
WKQ Coaches & Staff 113983384 https://groupme.com/join_group/113983384/gO1UAM6D 6
17U Elite Kings 113983492 https://groupme.com/join_group/113983492/yHjpK36E 5
17U Select Kings 113983493 https://groupme.com/join_group/113983493/2RONC4Nm 6
16U Elite Kings 113983494 https://groupme.com/join_group/113983494/P3oJXQks 5
17U Elite Queens 113983495 https://groupme.com/join_group/113983495/I5UwfDau 4
16U Elite Queens 113983496 https://groupme.com/join_group/113983496/jvSn5giy 4
17U Local Kings 113983497 https://groupme.com/join_group/113983497/efpXk7sk 9
16U Local Kings 113983498 https://groupme.com/join_group/113983498/YShtaYyL 5
17U Local Queens 113983499 https://groupme.com/join_group/113983499/TWcWGU4f —
16U Local Queens 113983500 https://groupme.com/join_group/113983500/UCsfZdjY —

Known Behaviors

  • Share links are permanent and reusable — anyone who clicks joins. Parent can forward to player.
  • Admin role promotion has no API endpoint — must be done manually in GroupMe app (9 taps for Marcus).
  • Adding by phone via API may not match existing GroupMe accounts — use share links instead.
  • DM API exists at POST /direct_messages with recipient_id and text fields. NOT documented in public API docs but works.
  • Initial DMs block links/emails: GroupMe returns 422 'links are restricted in initial DMs until approval is granted' if the message contains @ or .com patterns. Workaround: obfuscate emails as name (at) domain (dot) com.
  • File attachments work: POST file.groupme.com/v1/{group_id}/files accepts any file type (PDF, etc). Upload → poll status → send message with {"type": "file", "file_id": "..."} attachment. Undocumented endpoint.

Backlog

  • PreToolUse hook for GroupMe write operations (claude-custom#160 — in next_up on board-pal-e-agency)
  • Marcus: promote to admin on all 9 team groups (manual in GroupMe app)
  • Set up cron for outbox worker (POST /api/admin/process-outbox every 30s)
  • Fix reconciliation script nickname bug (commit to basketball-api)
  • QA nits: SDK (generic Exception, f-string query params), MCP (README, tests/__init__.py)
  • Re-enable ArgoCD auto-sync after pal-e-services #28 is fixed