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

{% @mermaid/diagram content="graph TD
subgraph "External Clients"
CLI\[CLI Tools]
CI\[CI/CD Systems]
WH\[Webhooks]
CD\[Codev Desktop]
end

```
subgraph "Edge Layer"
    CP[Caddy Proxy]
    TLS[TLS Termination]
    HC[Health Checks]
end

subgraph "Application Layer"
    API[API Gateway]
    WS[WebSocket Server]
    Tasks[Task Service]
end

CLI --> CP
CI --> CP
WH --> CP
CD --> CP

CP --> TLS
TLS --> API
TLS --> WS

API --> Tasks" %}
```

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.

{% @mermaid/diagram content="graph TD
subgraph "External Systems"
SF\[Salesforce Orgs]
GH\[GitHub/GitLab]
CI\[CI/CD Systems]
end

```
subgraph "Application Layer"
    API[API Gateway]
    Tasks[Task Service]
end

subgraph "Worker Layer"
    WM[Worker Manager]
    subgraph "Ephemeral Worker"
        CS[Credential Service]
        TH[Task Handler]
    end
end

CI --> API
API --> Tasks
Tasks --> WM
WM --> CS
TH --> SF
TH --> GH" %}
```

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.

{% @mermaid/diagram content="sequenceDiagram
participant Client
participant API
participant Task
participant Worker
participant Secrets
participant Salesforce

```
Client->>API: Request Operation
API->>Task: Create Task
Task->>Worker: Spawn Worker

Worker->>Secrets: Request Credentials
Secrets-->>Worker: Provide Credentials

Worker->>Salesforce: Establish Connection
Worker-->>Task: Report Progress
Task-->>Client: Status Updates

Worker->>Worker: Clear Credentials
Worker->>Worker: Terminate" %}
```

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.

{% @mermaid/diagram content="graph TD
subgraph "Webhook Sources"
SF\_E\[Salesforce Events]
GH\_E\[Git Events]
CI\_E\[CI/CD Events]
end

```
subgraph "Processing"
    Val[Validation]
    Sig[Signature Check]
    Rate[Rate Limiting]
end

subgraph "Task Creation"
    Map[Event Mapping]
    Task[Task Generation]
    Queue[Queue Selection]
end

SF_E --> Val
GH_E --> Val
CI_E --> Val

Val --> Sig
Sig --> Rate
Rate --> Map
Map --> Task
Task --> Queue" %}
```

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.

{% @mermaid/diagram content="sequenceDiagram
participant Client
participant Caddy
participant WebSocket
participant Task
participant Worker

```
Client->>Caddy: WebSocket Upgrade
Caddy->>WebSocket: Establish Connection

loop Task Execution
    Worker->>Task: Progress Update
    Task->>WebSocket: Status Change
    WebSocket->>Client: Real-time Update
end" %}
```

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.