Network Architecture & Integration System

Network Topology

All services run within a Docker bridge network. Caddy is the only service with a host network port binding — every other service communicates exclusively through internal Docker hostnames.

Caddy Routing

Caddy routes requests by path pattern.

Path	Destination	Purpose
/auth/v1/*	Supabase Kong > GoTrue	OAuth, SAML, token endpoints
/sfp/*	sfp Server	REST API
/*	sfp Server	Web application (SPA)

Administrative services (Hatchet dashboard, Supabase Studio, Verdaccio) are exposed on separate ports via a DNS-only admin subdomain with IP-based access controls.

When the API server is unavailable during updates, Caddy serves a maintenance page with a 503 status.

TLS

Caddy supports three certificate modes: Cloudflare origin certificates for deployments behind Cloudflare (Full Strict mode), Let's Encrypt automatic certificates for directly accessible instances, and custom certificates for environments with internal CAs.

Integration Providers

The server integrates with external systems through a provider abstraction. Each provider handles credential resolution, token management, and API client creation.

GitHub supports two authentication methods. GitHub App authentication (recommended) uses a registered private key to generate short-lived installation tokens scoped to specific repositories. Personal Access Token authentication is supported as a fallback. The server uses GitHub for repository access, pull request interaction, status checks, and webhook ingestion.

Azure DevOps uses personal access tokens for authentication. The server uses Azure DevOps for repository access, pull request interaction, pipeline triggering, and webhook ingestion.

Salesforce credentials include connected app details and authentication URLs. Workers use these to establish authenticated sessions with specific orgs for metadata operations, deployments, test execution, and sandbox management.

All credentials are registered through the integration API, encrypted with pgcrypto, and stored in the database.

Webhooks

Inbound webhooks from GitHub and Azure DevOps enter through Caddy, are validated for signature authenticity by the server, and dispatched as Hatchet workflows for execution. Any public ingress in front of Caddy must forward the raw request body and provider signature/event headers unchanged. For GitHub, that includes X-Hub-Signature-256, X-GitHub-Event, and X-GitHub-Delivery.

For SaaS providers such as GitHub.com, the webhook endpoint must be publicly reachable over HTTPS. Private hosts can remain private if a public ALB, API Gateway, or reverse proxy terminates HTTPS and forwards the request to Caddy inside the private network.

Supported events include push events (triggering builds or source tracking), pull request events (triggering validation, reviews, and environment provisioning), and issue comment events (supporting command-based interactions through PR comments).

The webhook handler returns 200 immediately after dispatching, without waiting for the workflow to complete. This keeps provider delivery requests within the short acknowledgement window expected by GitHub and similar SaaS webhook providers.

Private Package Registry

Verdaccio runs within the instance as a private npm registry. Hatchet workers use it during build and deployment operations for local package resolution. The registry is accessible through the admin subdomain for direct management.