huge documentaton restructure for docusaurus

docs/ops/deployment/join-token-analytics.md

@@ -0,0 +1,28 @@
+# Join Token Analytics & Alerting (SEC-GT-02)
+
+## Data Sources
+- Table `event_join_token_events` captures successes, failures, rate-limit hits, and uploads per join token.
+- Each row records route, device id, IP, HTTP status, and context for post-incident drill downs.
+- Logged automatically from `EventPublicController` for `/api/v1/events/*` and `/api/v1/gallery/*`.
+
+- Super Admin: Event resource → “Join Link / QR” modal now summarises total successes/failures, rate-limit hits, 24h volume, and last activity timestamp per token.
+- Tenant Admin: identical modal surface so operators can monitor invite health.
+
+## Alert Thresholds (initial)
+- **Rate limit spike**: >25 `token_rate_limited` entries for a token within 10 minutes → flag in monitoring (Grafana/Prometheus TODO).
+- **Failure ratio**: failure_count / success_count > 0.5 over rolling hour triggers warning for support follow-up.
+- **Inactivity**: tokens without access for >30 days should be reviewed; scheduled report TBD.
+
+Rate-limiter knobs (see `.env.example`):
+- `JOIN_TOKEN_FAILURE_LIMIT` / `JOIN_TOKEN_FAILURE_DECAY` — repeated invalid attempts before temporary block (default 10 tries per 5 min).
+- `JOIN_TOKEN_ACCESS_LIMIT` / `JOIN_TOKEN_ACCESS_DECAY` — successful request ceiling per token/IP (default 120 req per minute).
+- `JOIN_TOKEN_DOWNLOAD_LIMIT` / `JOIN_TOKEN_DOWNLOAD_DECAY` — download ceiling per token/IP (default 60 downloads per minute).
+
+## Follow-up Tasks
+1. Wire aggregated metrics into Grafana once metrics pipeline is ready (synthetic monitors pending SEC-GT-03).
+2. Implement scheduled command to email tenants a weekly digest of token activity and stale tokens.
+3. Consider anonymising device identifiers before long-term retention (privacy review).
+
+## Runbook Notes
+- Analytics table may grow quickly for high-traffic events; plan nightly prune job (keep 90 days).
+- Use `php artisan tinker` to inspect token activity: `EventJoinTokenEvent::where('event_join_token_id', $id)->latest()->limit(20)->get()`.