Developer Tools

F21.16 7 features

At a glance

Engineer-grade developer tools inside the console: ERD viewer, Swagger explorer with pre-injected sys-JWT, signed webhook tester, sandbox seed-data generator with SSE progress, two-person-approved write playground with hash-pinned pipelines, schema-diff between Beanie and Mongo, and a structured logs search with App Insights or in-process ringbuffer fallback.

How it works

Developer Tools sits behind `sys_engineer` and gives the team a way to reach into the platform without SSHing into anything. Audit prefix is `sys.dev-tools.*`; the runbook lives in `docs/engineering/operations/developer-tools.md`. The ERD viewer iframes the API container's `/erd` endpoints with a manifest from `GET /sys/dev/erd`, so the live diagram stays in sync with deployed Beanie models.

The API explorer is a Swagger UI with the operator's sys-JWT pre-injected via `preauthorizeApiKey` and an `X-Tenant-ID` selector, and probes are manually loggable through `POST /sys/dev/explorer/audit` so an engineer's debugging session leaves a trail. The webhook tester at `POST /sys/dev/webhooks/test` sends a HMAC-SHA-256-signed payload to a subscription's callback with a 10-second timeout and surfaces status, latency, signature, and response body — invaluable when a tenant integration breaks and the question is `did the request reach you`. The seed-data generator offers three presets (`minimal_realistic`, `load_test`, `stress`) with override counts; runs are async, progress streams via SSE at `GET /sys/dev/seed/{id}/events` with a 4-second poll fallback, and the target tenant defaults to sandbox so production never gets seeded by accident.

The query playground in write mode is the most carefully engineered piece: every pipeline must be approved by a second sys engineer, the approval is hash-pinned to the SHA-256 of the pipeline (so swapping the body after approval invalidates it), the approval has a 5-minute TTL, self-approval is blocked, and the run re-validates the hash before executing. Read-mode queries already exist via `/sys/audit/search`. Schema-diff at `GET /sys/dev/schema-diff` compares Beanie-declared indexes against live MongoDB and returns missing/extra/changed per collection plus a flat `drift_count`; the daily run flags drift before the next deploy.

Logs search at `GET /sys/dev/logs` accepts eight structured filters; in production it sources from App Insights, in dev it falls back to an in-process ringbuffer (maxlen 5 000) so engineers always have a logs surface even without the cloud telemetry path.

Key capabilities

ERD viewer iframed from API `/erd` with live Beanie manifest
Swagger explorer with pre-injected sys-JWT and tenant header selector; manual audit-log
Webhook tester with HMAC-SHA-256 signing and full request/response trace
Seed-data generator with three presets, async + SSE progress, sandbox-by-default
Two-person-approved write playground with hash-pinned pipelines and 5-minute TTL
Schema-diff: Beanie vs live Mongo indexes per collection with `drift_count`
Logs search with eight filters, App Insights primary and ringbuffer fallback

In practice

A backend engineer is debugging a tenant's webhook integration. He opens the webhook tester, picks the subscription, and clicks `Send`. The HMAC signature, timing, and response body return inline; the partner's endpoint replies 502 with a stack trace, so the bug is on their side.

Later the daily schema-diff job posts a `drift_count: 3` to Slack; he opens the report, sees a missing index on `payments.tenant_id`, and writes a write-playground pipeline to add it. A colleague reviews the pipeline, approves it (hash-pinned), and within five minutes he runs it. The audit log records both the approval and the run.

Features in this subsystem

ID	Status	Features
F21.16.01	Shipped	ERD viewer — visual graph of all collections + relationships. Iframe over the API container's /erd endpoints; manifest from GET /sys/dev/erd. ✅ PL-T136
F21.16.02	Shipped	API explorer — Swagger UI med pre-injected sys-JWT (preauthorizeApiKey) och valbar X-Tenant-ID. Manuell probe-loggning via POST /sys/dev/explorer/audit. Implemented (PL-T136)
F21.16.03	Shipped	Webhook tester — POST /sys/dev/webhooks/test skickar HMAC-SHA-256-signerad payload till abonnemangets callback med 10 s-timeout; visar status, latens, signatur och svar. Implemented (PL-T136)
F21.16.04	Shipped	Seed-data generator — tre presets (minimal_realistic, load_test, stress) med valbara override-counts. Async körning + SSE (GET /sys/dev/seed/{id}/events) + 4 s-poll. Sandbox-by-default. Implemented (PL-T136)
F21.16.05	Shipped	Query playground (write) — två-personers godkännande med hash-pinned pipeline (SHA-256), 5 min TTL, self-approval blockad, run re-validerar hashen. Read-mode finns sedan tidigare via /sys/audit/search. Implemented (PL-T136)
F21.16.06	Shipped	Schema-diff — GET /sys/dev/schema-diff jämför Beanie-deklarerade index mot live MongoDB; missing/extra/changed per collection + flat drift_count. Implemented (PL-T136)
F21.16.07	Shipped	Logs search — GET /sys/dev/logs med åtta strukturerade filter; App Insights-källa när konfigurerad, annars in-process ringbuffer (maxlen=5000). Implemented (PL-T136)