# 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/diagram content="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.

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.

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

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

The question should be specific, self-contained, and written in natural language.
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.