Architecture

XFlow sits between source applications and operators: apps emit signals (HTTP ingest, collector pulls) while humans interact through an authenticated Next.js console backed by PostgreSQL.

Multi-tenant isolation is enforced at the workspace layer—catalog data, events, and connections are keyed by workspace membership, not implicit trust.

Applications POST normalized JSON to the control-plane ingest route using per-connection bearer material. Payloads are validated, rate-limited, and either persisted or acknowledged as idempotent replays.

Bootstrap exchange exists for provider onboarding without a browser session; it is tightly scoped, rate-limited, and validated server-side.

Events share a single schema: app slug, environment, type, category, severity, titles, optional entity metadata, and timestamps. That uniformity is what makes cross-app triage possible.

Contract versioning allows providers to evolve payloads without breaking operator interpretations when both sides agree on a version.

HTTP APIs propagate request identifiers; clients may supply correlation headers. Responses echo a stable request ID for support and log joins.

Dedupe keys pair with database constraints and transactional advisory locks so duplicate deliveries surface as explicit skips instead of double rows.

Liveness-style checks prove the process is running; readiness gates signal whether an instance should receive traffic or background work.

XFlow exposes platform probes that must not leak tenant data, separate from authenticated JSON APIs that do.

PostgreSQL holds normalized events, dedupe metadata, ingest attempt telemetry, and workspace catalog rows. Collectors persist structured snapshots when integrations run.

Operator surfaces are server-rendered views and authenticated JSON routes that aggregate those tables—never raw ad hoc SQL in the browser.

Middleware protects dashboard pages and internal APIs. Only documented integration endpoints (ingest, bootstrap exchange, platform probes) are reachable without a browser session—and those have their own auth or emptiness guarantees.

Connection secrets are encrypted at rest; audit logging captures sensitive actions with workspace context.