Network Architecture & Integration System

This document describes the network surface through which clients reach sfp server and the integration surface through which the server interacts with external systems.

Edge Layer

Caddy serves as the edge entry point for an sfp server instance. It terminates TLS connections, routes traffic to the appropriate internal handlers based on host and path patterns, and applies baseline controls including request validation, rate limiting, and header normalization before requests reach the internal application network.

The internal network uses a Docker bridge topology where services communicate through a shared application network. This provides service isolation while enabling controlled communication between components. Caddy is the only service exposed to external traffic; all other services communicate exclusively through internal hostnames.

External System Integration

Integration traffic enters through the same edge layer as regular API calls. The difference lies in what happens after a request is accepted. The server creates an operation record, obtains the external system credentials required for that specific operation, and performs the external calls from the worker execution context rather than from the API service itself.

This design keeps the API service stateless with respect to external credentials. Workers fetch credentials just-in-time for their assigned tasks and clear them upon completion. The API schedules work and enforces authorization, but the actual external system access happens in isolated worker contexts.

Salesforce Integration

Salesforce operations use access tokens obtained specifically for each operation. The token is treated as a scoped runtime credential: acquired just-in-time, used to establish the Salesforce connection, and cleared when the operation finishes.

Credentials are stored outside the application network and fetched only by the worker that needs them. Each task runs in its own isolated worker boundary, limiting cross-task and cross-tenant credential exposure.

Webhook Processing

Webhooks provide an inbound trigger mechanism for external events. They enter through the edge layer, are validated for signature and rate limits, and are mapped into tasks that execute through the normal task processing pipeline.

When a webhook arrives, the edge terminates TLS and forwards it to the webhook handler. The handler validates the signature and request shape, maps the event into a task type, and enqueues it with an appropriate priority based on the event type and configured rules.

Real-time Updates

Real-time updates are delivered over WebSocket connections that are established through the same edge layer as the REST API. TLS termination and routing follow the same patterns. Workers emit progress and state changes during task execution, the task service projects these into client-visible channels, and subscribed clients receive updates as tasks run.

This enables clients to receive live feedback during long-running operations without polling. The WebSocket service maintains connection state and handles reconnection scenarios, ensuring clients can resume receiving updates after transient network interruptions.