Picklebot Architecture

How SMAD Picklebot fits together: the system context, the runtime map, the scheduled work, and the five sequences that matter. Two of the diagrams are computed from the repository every time this page is built; the rest are written by hand and checked against the code by the test suite, so what you see is what runs.

System context

Who talks to Picklebot and what Picklebot talks to. The group and its admins on WhatsApp, the club, the bank, and the Google Cloud and GitHub pieces that do the work.

flowchart LR
  players(["SMAD players and admins<br/>WhatsApp group, DMs, /pb commands"])
  greenapi["GREEN-API<br/>the bot's WhatsApp number"]
  gmail["Gmail<br/>Venmo and Zelle receipts"]
  club["The Athenaeum<br/>court booking site"]
  anthropic["Anthropic API<br/>intent parsing, post-game stories, release notes"]
  neon[("Neon Postgres<br/>aws-us-west-2: the system of record")]

  subgraph gcp["Google Cloud (smad-pickleball, us-west1)"]
    webhook["smad-whatsapp-webhook<br/>votes, state, forwards /pb"]
    picklebot["smad-picklebot<br/>every /pb command"]
    sender["whatsapp-message-sender<br/>Pub/Sub → GREEN-API, deduped"]
    venmo["venmo-sync-trigger<br/>Gmail watch → payments"]
    site["smad-site<br/>smadpicklebot.com"]
    api["smad-api<br/>FastAPI: /docs, /v1"]
    topic[("Pub/Sub<br/>whatsapp-messages")]
    firestore[("Firestore<br/>dedup, locks, audit")]
    bucket[("GCS smad-pickleball-reports<br/>JSON exports, site/ pages")]
    scheduler["Cloud Scheduler<br/>the nightly booking, the hourly clock, the sweeps"]
  end

  subgraph gha["GitHub Actions"]
    workflows["the workflows<br/>polls, reminders, booking, finance, dashboards, sweeps"]
  end

  subgraph ladder["The app's ladder (10/12/26): a rung above never runs a newer build than the one below"]
    build["desktop build<br/>artifact.py build: typecheck, suites, one web export"]
    dev["dev<br/>devlan.smadpicklebot.com, this desktop's proxy, the same files"]
  end

  players <-->|messages| greenapi
  greenapi -->|webhook, bearer token| webhook
  webhook -->|bearer token| picklebot
  picklebot --> topic
  webhook --> topic
  topic --> sender
  sender -->|send| greenapi
  gmail -->|Pub/Sub push| venmo
  venmo --> api
  picklebot --> api
  webhook --> api
  picklebot --> firestore
  sender --> firestore
  picklebot --> anthropic
  picklebot -->|dispatch| workflows
  scheduler -->|dispatch| workflows
  scheduler -->|the hourly tick, via Pub/Sub| api
  workflows --> api
  workflows --> topic
  workflows -->|exports, pages| bucket
  workflows -->|Playwright| club
  workflows --> anthropic
  bucket --> site
  players -->|browse| site
  players -->|the app| api
  api --> neon
  build -->|promoted first| dev
  dev -->|the push's gate: dev is serving it| bucket
  dev -->|/api, forwarded| api
source · docs/architecture/context.mmd
flowchart LR
  players(["SMAD players and admins<br/>WhatsApp group, DMs, /pb commands"])
  greenapi["GREEN-API<br/>the bot's WhatsApp number"]
  gmail["Gmail<br/>Venmo and Zelle receipts"]
  club["The Athenaeum<br/>court booking site"]
  anthropic["Anthropic API<br/>intent parsing, post-game stories, release notes"]
  neon[("Neon Postgres<br/>aws-us-west-2: the system of record")]

  subgraph gcp["Google Cloud (smad-pickleball, us-west1)"]
    webhook["smad-whatsapp-webhook<br/>votes, state, forwards /pb"]
    picklebot["smad-picklebot<br/>every /pb command"]
    sender["whatsapp-message-sender<br/>Pub/Sub → GREEN-API, deduped"]
    venmo["venmo-sync-trigger<br/>Gmail watch → payments"]
    site["smad-site<br/>smadpicklebot.com"]
    api["smad-api<br/>FastAPI: /docs, /v1"]
    topic[("Pub/Sub<br/>whatsapp-messages")]
    firestore[("Firestore<br/>dedup, locks, audit")]
    bucket[("GCS smad-pickleball-reports<br/>JSON exports, site/ pages")]
    scheduler["Cloud Scheduler<br/>the nightly booking, the hourly clock, the sweeps"]
  end

  subgraph gha["GitHub Actions"]
    workflows["the workflows<br/>polls, reminders, booking, finance, dashboards, sweeps"]
  end

  subgraph ladder["The app's ladder (10/12/26): a rung above never runs a newer build than the one below"]
    build["desktop build<br/>artifact.py build: typecheck, suites, one web export"]
    dev["dev<br/>devlan.smadpicklebot.com, this desktop's proxy, the same files"]
  end

  players <-->|messages| greenapi
  greenapi -->|webhook, bearer token| webhook
  webhook -->|bearer token| picklebot
  picklebot --> topic
  webhook --> topic
  topic --> sender
  sender -->|send| greenapi
  gmail -->|Pub/Sub push| venmo
  venmo --> api
  picklebot --> api
  webhook --> api
  picklebot --> firestore
  sender --> firestore
  picklebot --> anthropic
  picklebot -->|dispatch| workflows
  scheduler -->|dispatch| workflows
  scheduler -->|the hourly tick, via Pub/Sub| api
  workflows --> api
  workflows --> topic
  workflows -->|exports, pages| bucket
  workflows -->|Playwright| club
  workflows --> anthropic
  bucket --> site
  players -->|browse| site
  players -->|the app| api
  api --> neon
  build -->|promoted first| dev
  dev -->|the push's gate: dev is serving it| bucket
  dev -->|/api, forwarded| api

Runtime map (derived from Terraform and the Deploy workflow)

19 Cloud Functions, 16 Pub/Sub topics, 4 buckets and 19 Cloud Scheduler jobs, read from infra/terraform and .github/workflows/deploy.yml; each function's edges come from its own imports.

flowchart LR
  greenapi["GREEN-API (WhatsApp)"]
  gmail["Gmail watch"]
  gha["GitHub Actions workflows"]
  browser(["smadpicklebot.com visitors"])
  subgraph gcp["Google Cloud: smad-pickleball, us-west1 (infra/terraform)"]
    t_awards_dead_letter[("Pub/Sub awards-dead-letter")]
    t_ci_events[("Pub/Sub ci-events")]
    t_ci_events_dead_letter[("Pub/Sub ci-events-dead-letter")]
    t_desktop_tasks[("Pub/Sub desktop-tasks")]
    t_email_messages[("Pub/Sub email-messages")]
    t_email_messages_dead_letter[("Pub/Sub email-messages-dead-letter")]
    t_events[("Pub/Sub events")]
    t_events_dead_letter[("Pub/Sub events-dead-letter")]
    t_gmail_inbox_watch[("Pub/Sub gmail-inbox-watch")]
    t_play_console_events[("Pub/Sub play-console-events")]
    t_venmo_payment_emails[("Pub/Sub venmo-payment-emails")]
    t_venmo_payment_emails_dlq[("Pub/Sub venmo-payment-emails-dlq")]
    t_votes[("Pub/Sub votes")]
    t_votes_dead_letter[("Pub/Sub votes-dead-letter")]
    t_whatsapp_messages[("Pub/Sub whatsapp-messages")]
    t_whatsapp_messages_dlq[("Pub/Sub whatsapp-messages-dlq")]
    f_smad_api["smad-api<br/>HTTP"]
    f_smad_picklebot["smad-picklebot<br/>HTTP"]
    f_smad_whatsapp_webhook["smad-whatsapp-webhook<br/>HTTP"]
    f_whatsapp_message_sender["whatsapp-message-sender<br/>Pub/Sub whatsapp-messages"]
    f_venmo_sync_trigger["venmo-sync-trigger<br/>Pub/Sub venmo-payment-emails"]
    f_vote_writer["vote-writer<br/>Pub/Sub votes,"]
    f_event_worker["event-worker<br/>Pub/Sub votes,"]
    f_smad_site["smad-site<br/>HTTP"]
    f_alert_watcher["alert-watcher<br/>HTTP"]
    f_sentry_alerts["sentry-alerts<br/>HTTP"]
    f_app_store_watch["app-store-watch<br/>HTTP"]
    f_play_console_watch["play-console-watch<br/>HTTP"]
    f_push_decider["push-decider<br/>HTTP"]
    f_claude_runner["claude-runner<br/>HTTP"]
    f_smad_court_booking["smad-court-booking<br/>Cloud Run Job"]
    f_smad_commands_svc["smad-commands-svc<br/>Cloud Run Job"]
    f_smad_sync_members["smad-sync-members<br/>Cloud Run Job"]
    f_smad_watchdog["smad-watchdog<br/>Cloud Run Job"]
    f_smad_ci_metrics["smad-ci-metrics<br/>Cloud Run Job"]
    firestore[("Firestore")]
    b_smad_pickleball_function_source[("GCS smad-pickleball-function-source")]
    b_smad_pickleball_private_reports[("GCS smad-pickleball-private-reports")]
    b_smad_pickleball_reports[("GCS smad-pickleball-reports")]
    b_smad_pickleball_screenshots[("GCS smad-pickleball-screenshots")]
    subgraph sched["Cloud Scheduler"]
      s_account_delete_purge["account_delete_purge<br/>15 3 * * *"]
      s_alert_mailer_sweep["alert_mailer_sweep<br/>*/15 * * * *"]
      s_app_store_status["app_store_status<br/>5 9 * * *"]
      s_clock_hour["clock_hour<br/>5 * * * *"]
      s_court_booking_desktop["court_booking_desktop<br/>58 23 * * *"]
      s_court_booking_probe["court_booking_probe<br/>50 23 * * *"]
      s_court_booking_run["court_booking_run<br/>59 23 * * *"]
      s_court_booking_run_reverse["court_booking_run_reverse<br/>59 23 * * *"]
      s_join_requests_remind["join_requests_remind<br/>0 7 * * *"]
      s_keepalive["keepalive<br/>*/10 * * * *"]
      s_keepalive_api["keepalive_api<br/>*/10 * * * *"]
      s_keepalive_sentry_alerts["keepalive_sentry_alerts<br/>*/10 * * * *"]
      s_keepalive_site["keepalive_site<br/>*/10 * * * *"]
      s_more_jobs["more_jobs<br/>?"]
      s_push_receipts["push_receipts<br/>*/5 * * * *"]
      s_release_notes["release_notes<br/>0 8 * * *"]
      s_security_scan["security_scan<br/>37 8 * * 1"]
      s_sync_members_shadow["sync_members_shadow<br/>0,30 9 * * *"]
      s_watchdog["watchdog<br/>41 * * * *"]
    end
  end
  anthropic["Anthropic API"]
  neon[("Neon Postgres<br/>aws-us-west-2")]
  f_smad_api --> firestore
  f_smad_api -->|bearer token| f_smad_picklebot
  f_smad_api --> neon
  f_smad_picklebot --> firestore
  f_smad_picklebot --> t_whatsapp_messages
  f_smad_picklebot <--> b_smad_pickleball_screenshots
  greenapi -->|webhook, bearer token| f_smad_whatsapp_webhook
  f_smad_whatsapp_webhook --> firestore
  f_smad_whatsapp_webhook --> t_whatsapp_messages
  f_smad_whatsapp_webhook -->|bearer token| f_smad_picklebot
  t_whatsapp_messages --> f_whatsapp_message_sender
  f_whatsapp_message_sender -->|send| greenapi
  f_whatsapp_message_sender --> firestore
  t_venmo_payment_emails --> f_venmo_sync_trigger
  f_venmo_sync_trigger --> firestore
  t_votes_ --> f_vote_writer
  f_vote_writer --> firestore
  t_votes_ --> f_event_worker
  f_event_worker --> firestore
  f_smad_site --> firestore
  f_smad_site <--> b_smad_pickleball_private_reports
  f_smad_site <--> b_smad_pickleball_reports
  f_alert_watcher --> firestore
  f_sentry_alerts --> firestore
  f_app_store_watch --> firestore
  f_play_console_watch --> firestore
  f_claude_runner --> firestore
  f_smad_court_booking --> firestore
  f_smad_court_booking --> t_whatsapp_messages
  f_smad_watchdog <--> b_smad_pickleball_private_reports
  f_smad_watchdog <--> b_smad_pickleball_reports
  f_smad_ci_metrics <--> b_smad_pickleball_reports
  browser -->|/docs, /v1| f_smad_api
  gmail --> t_venmo_payment_emails
  s_court_booking_probe -->|run| f_smad_court_booking
  s_court_booking_run -->|run| f_smad_court_booking
  s_court_booking_run_reverse -->|run| f_smad_court_booking
  s_release_notes -->|release-notes.yml| gha
  s_security_scan -->|security-scan.yml| gha
  athenaeum["Athenaeum court site"]
  f_smad_api -->|browser| athenaeum
  f_smad_picklebot -->|browser| athenaeum
  f_smad_court_booking -->|browser| athenaeum
  f_smad_commands_svc -->|browser| athenaeum
  browser --> f_smad_site
  gha -->|exports, site/ pages| b_smad_pickleball_private_reports
  gha -->|exports, site/ pages| b_smad_pickleball_reports
source · computed by scripts/build-architecture.py
flowchart LR
  greenapi["GREEN-API (WhatsApp)"]
  gmail["Gmail watch"]
  gha["GitHub Actions workflows"]
  browser(["smadpicklebot.com visitors"])
  subgraph gcp["Google Cloud: smad-pickleball, us-west1 (infra/terraform)"]
    t_awards_dead_letter[("Pub/Sub awards-dead-letter")]
    t_ci_events[("Pub/Sub ci-events")]
    t_ci_events_dead_letter[("Pub/Sub ci-events-dead-letter")]
    t_desktop_tasks[("Pub/Sub desktop-tasks")]
    t_email_messages[("Pub/Sub email-messages")]
    t_email_messages_dead_letter[("Pub/Sub email-messages-dead-letter")]
    t_events[("Pub/Sub events")]
    t_events_dead_letter[("Pub/Sub events-dead-letter")]
    t_gmail_inbox_watch[("Pub/Sub gmail-inbox-watch")]
    t_play_console_events[("Pub/Sub play-console-events")]
    t_venmo_payment_emails[("Pub/Sub venmo-payment-emails")]
    t_venmo_payment_emails_dlq[("Pub/Sub venmo-payment-emails-dlq")]
    t_votes[("Pub/Sub votes")]
    t_votes_dead_letter[("Pub/Sub votes-dead-letter")]
    t_whatsapp_messages[("Pub/Sub whatsapp-messages")]
    t_whatsapp_messages_dlq[("Pub/Sub whatsapp-messages-dlq")]
    f_smad_api["smad-api<br/>HTTP"]
    f_smad_picklebot["smad-picklebot<br/>HTTP"]
    f_smad_whatsapp_webhook["smad-whatsapp-webhook<br/>HTTP"]
    f_whatsapp_message_sender["whatsapp-message-sender<br/>Pub/Sub whatsapp-messages"]
    f_venmo_sync_trigger["venmo-sync-trigger<br/>Pub/Sub venmo-payment-emails"]
    f_vote_writer["vote-writer<br/>Pub/Sub votes,"]
    f_event_worker["event-worker<br/>Pub/Sub votes,"]
    f_smad_site["smad-site<br/>HTTP"]
    f_alert_watcher["alert-watcher<br/>HTTP"]
    f_sentry_alerts["sentry-alerts<br/>HTTP"]
    f_app_store_watch["app-store-watch<br/>HTTP"]
    f_play_console_watch["play-console-watch<br/>HTTP"]
    f_push_decider["push-decider<br/>HTTP"]
    f_claude_runner["claude-runner<br/>HTTP"]
    f_smad_court_booking["smad-court-booking<br/>Cloud Run Job"]
    f_smad_commands_svc["smad-commands-svc<br/>Cloud Run Job"]
    f_smad_sync_members["smad-sync-members<br/>Cloud Run Job"]
    f_smad_watchdog["smad-watchdog<br/>Cloud Run Job"]
    f_smad_ci_metrics["smad-ci-metrics<br/>Cloud Run Job"]
    firestore[("Firestore")]
    b_smad_pickleball_function_source[("GCS smad-pickleball-function-source")]
    b_smad_pickleball_private_reports[("GCS smad-pickleball-private-reports")]
    b_smad_pickleball_reports[("GCS smad-pickleball-reports")]
    b_smad_pickleball_screenshots[("GCS smad-pickleball-screenshots")]
    subgraph sched["Cloud Scheduler"]
      s_account_delete_purge["account_delete_purge<br/>15 3 * * *"]
      s_alert_mailer_sweep["alert_mailer_sweep<br/>*/15 * * * *"]
      s_app_store_status["app_store_status<br/>5 9 * * *"]
      s_clock_hour["clock_hour<br/>5 * * * *"]
      s_court_booking_desktop["court_booking_desktop<br/>58 23 * * *"]
      s_court_booking_probe["court_booking_probe<br/>50 23 * * *"]
      s_court_booking_run["court_booking_run<br/>59 23 * * *"]
      s_court_booking_run_reverse["court_booking_run_reverse<br/>59 23 * * *"]
      s_join_requests_remind["join_requests_remind<br/>0 7 * * *"]
      s_keepalive["keepalive<br/>*/10 * * * *"]
      s_keepalive_api["keepalive_api<br/>*/10 * * * *"]
      s_keepalive_sentry_alerts["keepalive_sentry_alerts<br/>*/10 * * * *"]
      s_keepalive_site["keepalive_site<br/>*/10 * * * *"]
      s_more_jobs["more_jobs<br/>?"]
      s_push_receipts["push_receipts<br/>*/5 * * * *"]
      s_release_notes["release_notes<br/>0 8 * * *"]
      s_security_scan["security_scan<br/>37 8 * * 1"]
      s_sync_members_shadow["sync_members_shadow<br/>0,30 9 * * *"]
      s_watchdog["watchdog<br/>41 * * * *"]
    end
  end
  anthropic["Anthropic API"]
  neon[("Neon Postgres<br/>aws-us-west-2")]
  f_smad_api --> firestore
  f_smad_api -->|bearer token| f_smad_picklebot
  f_smad_api --> neon
  f_smad_picklebot --> firestore
  f_smad_picklebot --> t_whatsapp_messages
  f_smad_picklebot <--> b_smad_pickleball_screenshots
  greenapi -->|webhook, bearer token| f_smad_whatsapp_webhook
  f_smad_whatsapp_webhook --> firestore
  f_smad_whatsapp_webhook --> t_whatsapp_messages
  f_smad_whatsapp_webhook -->|bearer token| f_smad_picklebot
  t_whatsapp_messages --> f_whatsapp_message_sender
  f_whatsapp_message_sender -->|send| greenapi
  f_whatsapp_message_sender --> firestore
  t_venmo_payment_emails --> f_venmo_sync_trigger
  f_venmo_sync_trigger --> firestore
  t_votes_ --> f_vote_writer
  f_vote_writer --> firestore
  t_votes_ --> f_event_worker
  f_event_worker --> firestore
  f_smad_site --> firestore
  f_smad_site <--> b_smad_pickleball_private_reports
  f_smad_site <--> b_smad_pickleball_reports
  f_alert_watcher --> firestore
  f_sentry_alerts --> firestore
  f_app_store_watch --> firestore
  f_play_console_watch --> firestore
  f_claude_runner --> firestore
  f_smad_court_booking --> firestore
  f_smad_court_booking --> t_whatsapp_messages
  f_smad_watchdog <--> b_smad_pickleball_private_reports
  f_smad_watchdog <--> b_smad_pickleball_reports
  f_smad_ci_metrics <--> b_smad_pickleball_reports
  browser -->|/docs, /v1| f_smad_api
  gmail --> t_venmo_payment_emails
  s_court_booking_probe -->|run| f_smad_court_booking
  s_court_booking_run -->|run| f_smad_court_booking
  s_court_booking_run_reverse -->|run| f_smad_court_booking
  s_release_notes -->|release-notes.yml| gha
  s_security_scan -->|security-scan.yml| gha
  athenaeum["Athenaeum court site"]
  f_smad_api -->|browser| athenaeum
  f_smad_picklebot -->|browser| athenaeum
  f_smad_court_booking -->|browser| athenaeum
  f_smad_commands_svc -->|browser| athenaeum
  browser --> f_smad_site
  gha -->|exports, site/ pages| b_smad_pickleball_private_reports
  gha -->|exports, site/ pages| b_smad_pickleball_reports

Scheduled work (derived from the workflows)

17 workflows: what starts each one (Cloud Scheduler, picklebot, a GitHub cron, a push, another workflow), and what it publishes to the reports bucket.

flowchart LR
  sched["Cloud Scheduler"]
  pb["picklebot (/pb)"]
  cron["GitHub cron"]
  push["push to main"]
  ops["ops/*.txt levers"]
  subgraph wf["GitHub Actions (.github/workflows)"]
    w_app_yml["app.yml"]
    w_clerk_config_yml["clerk-config.yml"]
    w_deploy_yml["deploy.yml"]
    w_game_plan_runner_yml["game-plan-runner.yml"]
    w_last_call_runner_yml["last-call-runner.yml"]
    w_lights_reminder_runner_yml["lights-reminder-runner.yml"]
    w_promote_yml["promote.yml"]
    w_release_notes_yml["release-notes.yml"]
    w_security_scan_yml["security-scan.yml"]
    w_sim_smoke_yml["sim-smoke.yml"]
    w_site_pages_yml["site-pages.yml"]
    w_store_upload_yml["store-upload.yml"]
    w_terraform_yml["terraform.yml"]
    w_tests_image_yml["tests-image.yml"]
    w_tests_yml["tests.yml"]
    w_venmo_sync_yml["venmo-sync.yml"]
    w_workflow_watchdog_yml["workflow-watchdog.yml"]
  end
  subgraph gcs["GCS smad-pickleball-reports (what the workflows publish)"]
    o_smad_pickleball_reports_release_notes_weekly_json[("release-notes-weekly.json")]
    o_smad_pickleball_reports_release_notes_json[("release-notes.json")]
    o_smad_pickleball_reports_site_architecture_html[("site/architecture.html")]
    o_smad_pickleball_reports_site_buildpipeline_html[("site/buildpipeline.html")]
    o_smad_pickleball_reports_site_releasedashboard_html[("site/releasedashboard.html")]
    o_smad_pickleball_reports_test_results_json[("test-results.json")]
    o_smad_pickleball_terraform_state_plans[("plans")]
    o_smad_pickleball_terraform_state_terraform_state_default_tflock[("terraform/state/default.tflock")]
  end
  push --> w_app_yml
  push --> w_clerk_config_yml
  push --> w_deploy_yml
  sched -->|0 8 * * *| w_release_notes_yml
  w_release_notes_yml --> o_smad_pickleball_reports_release_notes_weekly_json
  w_release_notes_yml --> o_smad_pickleball_reports_release_notes_json
  w_release_notes_yml --> o_smad_pickleball_reports_site_architecture_html
  w_release_notes_yml --> o_smad_pickleball_reports_site_buildpipeline_html
  w_release_notes_yml --> o_smad_pickleball_reports_site_releasedashboard_html
  sched -->|37 8 * * 1| w_security_scan_yml
  push --> w_site_pages_yml
  push --> w_terraform_yml
  w_terraform_yml --> o_smad_pickleball_terraform_state_plans
  w_terraform_yml --> o_smad_pickleball_terraform_state_terraform_state_default_tflock
  push --> w_tests_image_yml
  push --> w_tests_yml
  w_tests_yml --> o_smad_pickleball_reports_test_results_json
source · computed by scripts/build-architecture.py
flowchart LR
  sched["Cloud Scheduler"]
  pb["picklebot (/pb)"]
  cron["GitHub cron"]
  push["push to main"]
  ops["ops/*.txt levers"]
  subgraph wf["GitHub Actions (.github/workflows)"]
    w_app_yml["app.yml"]
    w_clerk_config_yml["clerk-config.yml"]
    w_deploy_yml["deploy.yml"]
    w_game_plan_runner_yml["game-plan-runner.yml"]
    w_last_call_runner_yml["last-call-runner.yml"]
    w_lights_reminder_runner_yml["lights-reminder-runner.yml"]
    w_promote_yml["promote.yml"]
    w_release_notes_yml["release-notes.yml"]
    w_security_scan_yml["security-scan.yml"]
    w_sim_smoke_yml["sim-smoke.yml"]
    w_site_pages_yml["site-pages.yml"]
    w_store_upload_yml["store-upload.yml"]
    w_terraform_yml["terraform.yml"]
    w_tests_image_yml["tests-image.yml"]
    w_tests_yml["tests.yml"]
    w_venmo_sync_yml["venmo-sync.yml"]
    w_workflow_watchdog_yml["workflow-watchdog.yml"]
  end
  subgraph gcs["GCS smad-pickleball-reports (what the workflows publish)"]
    o_smad_pickleball_reports_release_notes_weekly_json[("release-notes-weekly.json")]
    o_smad_pickleball_reports_release_notes_json[("release-notes.json")]
    o_smad_pickleball_reports_site_architecture_html[("site/architecture.html")]
    o_smad_pickleball_reports_site_buildpipeline_html[("site/buildpipeline.html")]
    o_smad_pickleball_reports_site_releasedashboard_html[("site/releasedashboard.html")]
    o_smad_pickleball_reports_test_results_json[("test-results.json")]
    o_smad_pickleball_terraform_state_plans[("plans")]
    o_smad_pickleball_terraform_state_terraform_state_default_tflock[("terraform/state/default.tflock")]
  end
  push --> w_app_yml
  push --> w_clerk_config_yml
  push --> w_deploy_yml
  sched -->|0 8 * * *| w_release_notes_yml
  w_release_notes_yml --> o_smad_pickleball_reports_release_notes_weekly_json
  w_release_notes_yml --> o_smad_pickleball_reports_release_notes_json
  w_release_notes_yml --> o_smad_pickleball_reports_site_architecture_html
  w_release_notes_yml --> o_smad_pickleball_reports_site_buildpipeline_html
  w_release_notes_yml --> o_smad_pickleball_reports_site_releasedashboard_html
  sched -->|37 8 * * 1| w_security_scan_yml
  push --> w_site_pages_yml
  push --> w_terraform_yml
  w_terraform_yml --> o_smad_pickleball_terraform_state_plans
  w_terraform_yml --> o_smad_pickleball_terraform_state_terraform_state_default_tflock
  push --> w_tests_image_yml
  push --> w_tests_yml
  w_tests_yml --> o_smad_pickleball_reports_test_results_json

A /pb command

From the keyboard to the reply: the webhook authenticates GREEN-API, picklebot authenticates the webhook, the intent is parsed, the database is read or written through the API, and the reply goes out through the one sender.

sequenceDiagram
  autonumber
  actor Member
  participant GA as GREEN-API
  participant WH as smad-whatsapp-webhook<br/>webhook()
  participant PB as smad-picklebot<br/>picklebot_webhook()
  participant AI as Anthropic API
  participant SH as smad-api (Neon)
  participant GH as Cloud Run Jobs<br/>smad-daily, smad-commands, ...
  participant PS as Pub/Sub<br/>whatsapp-messages
  participant SN as whatsapp-message-sender

  Member->>GA: "/pb match 14 11-9"
  GA->>WH: POST incomingMessageReceived (Authorization: Bearer webhook token)
  WH->>WH: is this chat the group, a DM, Admin Dinkers? is the sender an admin?
  WH->>PB: forward_to_picklebot(): POST {command, chatId, sender, is_admin_group} + the same bearer token
  PB->>PB: refuse without the token, and refuse a chat id that is not a WhatsApp id
  PB->>AI: parse_intent_with_claude() (a regex fast path answers the common shapes first)
  AI-->>PB: {intent, params}
  PB->>PB: process_command(): admin gate for actions, roster gate for a stranger's DM
  PB->>SH: read the roster / write the ledger row (match, payment, DUPR change)
  opt an action that runs elsewhere (book a court, cancel a game, redraw a dashboard)
    PB->>GH: _run_job(): a Cloud Run Job execution, REPLY_CHAT_ID in its env
  end
  PB->>PS: publish_whatsapp_message(reply, correlation_id)
  PS->>SN: push
  SN->>SN: claim_message(): Firestore dedup by correlation_id
  SN->>GA: send_text_message()
  GA-->>Member: the reply
source · docs/architecture/seq-pb-command.mmd
sequenceDiagram
  autonumber
  actor Member
  participant GA as GREEN-API
  participant WH as smad-whatsapp-webhook<br/>webhook()
  participant PB as smad-picklebot<br/>picklebot_webhook()
  participant AI as Anthropic API
  participant SH as smad-api (Neon)
  participant GH as Cloud Run Jobs<br/>smad-daily, smad-commands, ...
  participant PS as Pub/Sub<br/>whatsapp-messages
  participant SN as whatsapp-message-sender

  Member->>GA: "/pb match 14 11-9"
  GA->>WH: POST incomingMessageReceived (Authorization: Bearer webhook token)
  WH->>WH: is this chat the group, a DM, Admin Dinkers? is the sender an admin?
  WH->>PB: forward_to_picklebot(): POST {command, chatId, sender, is_admin_group} + the same bearer token
  PB->>PB: refuse without the token, and refuse a chat id that is not a WhatsApp id
  PB->>AI: parse_intent_with_claude() (a regex fast path answers the common shapes first)
  AI-->>PB: {intent, params}
  PB->>PB: process_command(): admin gate for actions, roster gate for a stranger's DM
  PB->>SH: read the roster / write the ledger row (match, payment, DUPR change)
  opt an action that runs elsewhere (book a court, cancel a game, redraw a dashboard)
    PB->>GH: _run_job(): a Cloud Run Job execution, REPLY_CHAT_ID in its env
  end
  PB->>PS: publish_whatsapp_message(reply, correlation_id)
  PS->>SN: push
  SN->>SN: claim_message(): Firestore dedup by correlation_id
  SN->>GA: send_text_message()
  GA-->>Member: the reply

A poll vote

The weekly poll is a GitHub Actions job; every tap on it is a webhook that lands in the database.

sequenceDiagram
  autonumber
  participant GH as Cloud Run Job<br/>smad-daily (poll day)
  participant CLI as smad-whatsapp.py
  participant API as smad-api (Neon)
  participant GA as GREEN-API
  actor Member
  participant WH as smad-whatsapp-webhook<br/>webhook()
  participant Q as Pub/Sub votes<br/>vote-writer

  GH->>CLI: the weekly poll (the game days from the booking list and the club's reservations)
  CLI->>API: the week's games
  CLI->>GA: sendPoll to the SMAD group
  GA->>WH: pollMessage webhook (the poll's id, question and options)
  Member->>GA: taps a day (or "I can't play this week")
  GA->>WH: pollUpdateMessage (every option's current voters)
  WH->>WH: handle_poll_update(): newest poll only, each voter's latest choice
  WH->>API: record_poll_vote(): the poll answer, then the voter's Last Voted
  WH->>Q: update_poll_votes(): each game's In or Out, queued
  Q->>API: the vote-writer writes the votes
source · docs/architecture/seq-vote.mmd
sequenceDiagram
  autonumber
  participant GH as Cloud Run Job<br/>smad-daily (poll day)
  participant CLI as smad-whatsapp.py
  participant API as smad-api (Neon)
  participant GA as GREEN-API
  actor Member
  participant WH as smad-whatsapp-webhook<br/>webhook()
  participant Q as Pub/Sub votes<br/>vote-writer

  GH->>CLI: the weekly poll (the game days from the booking list and the club's reservations)
  CLI->>API: the week's games
  CLI->>GA: sendPoll to the SMAD group
  GA->>WH: pollMessage webhook (the poll's id, question and options)
  Member->>GA: taps a day (or "I can't play this week")
  GA->>WH: pollUpdateMessage (every option's current voters)
  WH->>WH: handle_poll_update(): newest poll only, each voter's latest choice
  WH->>API: record_poll_vote(): the poll answer, then the voter's Last Voted
  WH->>Q: update_poll_votes(): each game's In or Out, queued
  Q->>API: the vote-writer writes the votes

A payment

A Venmo or Zelle receipt in Gmail becomes a recorded payment and a thank-you, deduped twice.

sequenceDiagram
  autonumber
  actor Member
  participant Bank as Venmo / Bank of America
  participant GM as Gmail (labels: Venmo, zelle)
  participant PS as Pub/Sub<br/>gmail-inbox-watch
  participant VT as venmo-sync-trigger<br/>venmo_email_trigger()
  participant VA as Venmo API
  participant API as smad-api (Neon)
  participant WA as WhatsApp (via the sender)

  Member->>Bank: pays court fees
  Bank->>GM: receipt email
  GM->>PS: Gmail watch notification (at least once: ~36% arrive twice)
  PS->>VT: push
  VT->>VT: try_acquire_sync_lock() (Firestore, 90 s)
  par Venmo
    VT->>VA: sync_venmo(): recent transactions by the roster's Venmo handle or name
  and Zelle
    VT->>GM: sync_zelle_emails(): From must be the bank's alert domain, amount under the cap
  end
  VT->>API: record_payment(): the payment (transaction id = the dedup key), Last Paid
  VT->>WA: a thank-you DM (the group gets the week's summary from the smad-payment-sweep job)
source · docs/architecture/seq-payment.mmd
sequenceDiagram
  autonumber
  actor Member
  participant Bank as Venmo / Bank of America
  participant GM as Gmail (labels: Venmo, zelle)
  participant PS as Pub/Sub<br/>gmail-inbox-watch
  participant VT as venmo-sync-trigger<br/>venmo_email_trigger()
  participant VA as Venmo API
  participant API as smad-api (Neon)
  participant WA as WhatsApp (via the sender)

  Member->>Bank: pays court fees
  Bank->>GM: receipt email
  GM->>PS: Gmail watch notification (at least once: ~36% arrive twice)
  PS->>VT: push
  VT->>VT: try_acquire_sync_lock() (Firestore, 90 s)
  par Venmo
    VT->>VA: sync_venmo(): recent transactions by the roster's Venmo handle or name
  and Zelle
    VT->>GM: sync_zelle_emails(): From must be the bank's alert domain, amount under the cap
  end
  VT->>API: record_payment(): the payment (transaction id = the dedup key), Last Paid
  VT->>WA: a thank-you DM (the group gets the week's summary from the smad-payment-sweep job)

The nightly court booking

Cloud Scheduler just before the club's 12:01 AM release, or an admin's confirmation link, to Playwright on the club's site.

sequenceDiagram
  autonumber
  participant CS as Cloud Scheduler<br/>court-booking-job (58 23 * * *)
  participant PB as smad-picklebot<br/>execute_book_court()
  participant GH as Cloud Run Job<br/>smad-court-booking
  participant CB as court-booking.py<br/>AthenaeumBooking
  participant Club as The Athenaeum (ClubAccess)
  participant WA as WhatsApp (via the sender)

  alt nightly
    CS->>GH: run `book` and `book-reverse` (BOOKING_LIST: the weekly slots, North and South first at once)
  else by hand from chat
    PB->>PB: handle_confirmation(): the admin clicked the one-time link
    PB->>GH: run with --booking-date-time, --court, --duration and --reply-chat-id, each its own argument
  end
  GH->>CB: Playwright, headless Chromium, the club login from Secret Manager
  CB->>Club: log in, open the day, the court's slot
  alt the slot is open
    CB->>Club: book_court(): fill the form, submit
    Club-->>CB: confirmation
  else inside the club's 12-hour window
    CB-->>CB: "call the Athenaeum front desk" (the server refuses, no form opens)
  end
  CB->>WA: the result to Admin Dinkers (or the chat that asked). Nothing ever goes to the club from the bot
source · docs/architecture/seq-booking.mmd
sequenceDiagram
  autonumber
  participant CS as Cloud Scheduler<br/>court-booking-job (58 23 * * *)
  participant PB as smad-picklebot<br/>execute_book_court()
  participant GH as Cloud Run Job<br/>smad-court-booking
  participant CB as court-booking.py<br/>AthenaeumBooking
  participant Club as The Athenaeum (ClubAccess)
  participant WA as WhatsApp (via the sender)

  alt nightly
    CS->>GH: run `book` and `book-reverse` (BOOKING_LIST: the weekly slots, North and South first at once)
  else by hand from chat
    PB->>PB: handle_confirmation(): the admin clicked the one-time link
    PB->>GH: run with --booking-date-time, --court, --duration and --reply-chat-id, each its own argument
  end
  GH->>CB: Playwright, headless Chromium, the club login from Secret Manager
  CB->>Club: log in, open the day, the court's slot
  alt the slot is open
    CB->>Club: book_court(): fill the form, submit
    Club-->>CB: confirmation
  else inside the club's 12-hour window
    CB-->>CB: "call the Athenaeum front desk" (the server refuses, no form opens)
  end
  CB->>WA: the result to Admin Dinkers (or the chat that asked). Nothing ever goes to the club from the bot

A post-game refit

From the night's matches to the ratings, the kept story, the export and the published dashboard.

sequenceDiagram
  autonumber
  actor Admin
  participant PB as smad-picklebot
  participant SH as smad-api (Neon)
  participant AI as Anthropic API
  participant GH as Cloud Run Job<br/>smad-commands dupr-dashboard
  participant GCS as GCS smad-pickleball-reports
  participant Site as smad-site<br/>/dupr

  Admin->>PB: "/pb match 14 11-9" (all game long)
  PB->>SH: handle_record_match() → record_match(): a Win Loss Log row
  Admin->>PB: "/pb post game"
  PB->>SH: compute_smad_dupr(): fit_ratings() over every scored match (ridge, learned half-life)
  PB->>SH: SMAD DUPR Log rows (changes only), the report in the SMAD DUPR reports
  PB->>AI: the night's story, written once, kept in the SMAD DUPR analyses
  PB->>GH: _run_command(['dupr-dashboard'])
  GH->>SH: export-smad-dupr-data.py: build_payload() (names, ratings, pair edges, never a phone or an email)
  GH->>GCS: smad-dupr.json
  GH->>GH: build-smad-dupr-dashboard.py: main(), then site_page.standalone()
  GH->>GCS: site/dupr.html
  Site->>GCS: page_body(): fetch, cache briefly
  Admin->>Site: smadpicklebot.com/dupr, a minute or two after the refit
source · docs/architecture/seq-refit.mmd
sequenceDiagram
  autonumber
  actor Admin
  participant PB as smad-picklebot
  participant SH as smad-api (Neon)
  participant AI as Anthropic API
  participant GH as Cloud Run Job<br/>smad-commands dupr-dashboard
  participant GCS as GCS smad-pickleball-reports
  participant Site as smad-site<br/>/dupr

  Admin->>PB: "/pb match 14 11-9" (all game long)
  PB->>SH: handle_record_match() → record_match(): a Win Loss Log row
  Admin->>PB: "/pb post game"
  PB->>SH: compute_smad_dupr(): fit_ratings() over every scored match (ridge, learned half-life)
  PB->>SH: SMAD DUPR Log rows (changes only), the report in the SMAD DUPR reports
  PB->>AI: the night's story, written once, kept in the SMAD DUPR analyses
  PB->>GH: _run_command(['dupr-dashboard'])
  GH->>SH: export-smad-dupr-data.py: build_payload() (names, ratings, pair edges, never a phone or an email)
  GH->>GCS: smad-dupr.json
  GH->>GH: build-smad-dupr-dashboard.py: main(), then site_page.standalone()
  GH->>GCS: site/dupr.html
  Site->>GCS: page_body(): fetch, cache briefly
  Admin->>Site: smadpicklebot.com/dupr, a minute or two after the refit

How this page stays true

The runtime and scheduled-work maps are derived by scripts/build-architecture.py from infra/terraform and .github/workflows on every build. The hand-authored diagrams in docs/architecture/ each list the files and functions they describe in %% ref: lines, and tests/test-architecture.py fails when one of them no longer exists, or when the README's copy of the context diagram differs from the file. The page is republished by site-pages.yml whenever any of those sources change.