> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp-server/architecture-overview/sfp-server-architecture-overview-beta/network-architecture-and-integration-system.md).

# 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.

```mermaid
graph TD
    subgraph "External"
        Clients["CLI · Web App · CI/CD"]
        Webhooks["GitHub · Azure DevOps"]
    end

    subgraph "Host Network"
        Caddy["Caddy :443"]
    end

    subgraph "Docker Bridge"
        API["sfp Server :3029"]
        Kong["Supabase Kong :8000"]
        GoTrue["GoTrue :9999"]
        Hatchet["Hatchet Engine :7070"]
        Workers["Workers"]
        PG["PostgreSQL :5432"]
        VM["VictoriaMetrics"]
        VL["VictoriaLogs"]
        Verdaccio["Verdaccio :4873"]
    end

    Clients --> Caddy
    Webhooks --> Caddy
    Caddy -->|"/auth/v1/*"| Kong
    Caddy -->|"/sfp/* · /*"| API
    Kong --> GoTrue
    API --> Kong
    API --> Hatchet
    Workers --> API
```

## 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp-server/architecture-overview/sfp-server-architecture-overview-beta/network-architecture-and-integration-system.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.