Diagnose before reading code.
| Symptom | First move |
|---|---|
| Message stuck on the sending clock | Run python -m app.cli diagnose-stuck-sends. |
| Tags visible in one place but not another | Run python -m app.cli reconcile-tags. |
| Deploy stalled or component unhealthy | Use doctl apps list-deployments, doctl apps get-deployment, and component logs. Do not stack another deploy on top. |
| Connector CPU high | Drain media/avatar backlog in BullMQ. CPU tracks media volume. |
| Cloud API send one-grey-tick forever | Check whether the recipient is @lid or @g.us; always route through services/transport.py. |
| History or media recovery times out | Make sure the paired phone is awake and reachable. |
Useful CLI commands live under python -m app.cli from apps/api: seed, create-superuser, backfill-contact-phones, merge-username-contacts, reconcile-tags, and diagnose-stuck-sends.