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| apiRuntime 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_reportsScheduled 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_jsonA /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 replyA 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 botA 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.