# Admin capabilities and diagnostics

Platform admins use /admin/* (session + RequirePlatformAdmin). Support desk staff get ticket routes only (RequireSupportDesk).

## Useful admin APIs

| Path | Purpose |
|------|---------|
| GET /api/admin/diagnostics | Health: DB, queue, cache, storage, mail; config sanity (booleans only); recent job/AI failures |
| GET /api/admin/analytics | Operational metrics dashboard data |
| GET /api/admin/readiness | Cutover hypercare: must_set_password, companies without admin/plan |
| GET /api/admin/jobs | Recent processing_jobs |
| POST /api/admin/jobs/stuck-cleanup | Stuck running jobs cleanup |
| GET/PUT /api/admin/settings | Platform settings (secrets masked on GET) |
| GET/POST /api/admin/support/kb/articles | Support Knowledge CRUD |
| GET/PUT /api/admin/support/auto-config | FAQ + AI auto-reply switchboard |
| Users / companies / plans / credits | Org + billing admin |

UI: /admin/support/knowledge; diagnostics and analytics under the admin shell.

## Diagnose a stuck process

```mermaid
flowchart TD
  A[Job stuck or failed] --> B{Worker running?}
  B -->|No| C["Start: go run ./cmd/worker"]
  B -->|Yes| D["GET /api/admin/diagnostics"]
  D --> E{queue.failed or stuck_running?}
  E -->|Yes| F["GET /api/admin/jobs + stuck-cleanup"]
  E -->|No| G["Check /readyz + company credits"]
  F --> H["Retry job or re-POST /products/process"]
```

### Checklist

1. GET /healthz (liveness) and GET /readyz (Postgres + maintenance/read_only flags).  
2. GET /api/admin/diagnostics — overall ok|degraded|fail; never expect secrets in the payload.  
3. Confirm **worker** process is up (API alone does not drain processing).  
4. Filter recent failures: ?status=failed&failures_limit=25.  
5. Support auto AI: ticket auto_reply_status, /admin/support inbox flag=needs_human, AI role support under /admin/settings.  
6. Cutover: GET /api/admin/readiness before DNS switch.

Diagnostics intentionally excludes marketing charts — use analytics for trends, diagnostics for troubleshooting.

Sources: apps/api/internal/httpapi/admin_diagnostics_handlers.go, server.go admin routes.