# sfp-server: Architecture Overview (Beta)

## Introduction

`sfp server` is a long-running, API-driven platform that the `sfp` CLI and other clients communicate with. It provides a REST API for automation that can run outside a single CI/CD job, while enforcing strict security boundaries and operational isolation. The platform is designed to preserve strong isolation between tenants and tasks while providing real-time visibility into work as it happens.

## Core Principles

The architecture is guided by three foundational ideas that manifest throughout the system.

**Dedicated Instance Isolation.** Each organization runs in its own dedicated compute instance. Isolation is not only logical through namespaces and tenants, but also infrastructural with separate containers, resources, and runtime boundaries per instance.

**Ephemeral Task Execution.** Work is executed using an ephemeral processing model where tasks run in single-use worker processes that start from a clean image, receive only the credentials required for that task, and terminate upon completion. This minimizes cross-task contamination and keeps the blast radius small.

**Real-time State.** Instead of relying on Git as a state store, the server centralizes operational state in a database to enable real-time visibility, consistent coordination, and security controls such as row-level security.

## System Architecture

The platform implements a layered architecture where each layer has focused responsibilities.

{% @mermaid/diagram content="flowchart TB
subgraph ClientLayer\[Client Layer]
CLI\[SFP CLI]
IDE\[VSCode/IDE]
CI\[CI/CD Systems]
CD\[Codev Desktop]
end

```
subgraph EdgeLayer[Edge Layer]
    CP[Caddy Proxy]
    TLS[TLS Termination]
    WH[Webhook Handler]
end

subgraph AppLayer[Application Layer]
    API[API Gateway]
    Auth[Auth Service]
    Tasks[Task Service]
    WS[WebSocket Service]
end

subgraph ProcessLayer[Processing Layer]
    Queue[Task Queues]
    Workers[Worker Pool]
    Cache[Redis Cache]
end

subgraph StorageLayer[Storage Layer]
    DB[(Supabase DB)]
end

ClientLayer --> EdgeLayer
EdgeLayer --> AppLayer
AppLayer --> ProcessLayer
ProcessLayer --> StorageLayer" %}
```

The **edge layer** terminates TLS, routes requests, and applies baseline protections before traffic reaches internal services. The **application layer** hosts the API and supporting services for authentication, orchestration, and real-time updates. The **processing layer** runs workers and queues, enforcing the ephemeral execution model and isolating task runtimes. The **storage layer** persists system state and provides supporting infrastructure for secrets and caching.

## Service Model

At a high level, the API service acts as the control plane, owning authentication, coordination, and user-facing APIs. Workers form the data plane that executes tasks. The API surface is grouped by capability (auth, tasks, documents, key/value, Salesforce auth, webhooks), but all groups follow the same pattern of explicit boundaries, consistent security controls, and shared state in the database.

Task execution is organized around a priority queue model with critical, normal, and batch queues. The platform supports immediate, scheduled, and recurring workloads. It also exposes persistence primitives used by higher-level features including a document store with collections and versioning, and a key-value store for fast operational reads and writes.

## Deployment Model

`sfp server` can be deployed as a FLXBL-managed instance or a self-managed instance. In both models, each organization runs on its own dedicated machine with enough resources to run the full Docker Compose stack (8GB RAM minimum). The system is operationally a small set of cooperating containers: an edge proxy, an API control plane, worker pools, and supporting infrastructure including Redis and Supabase.

For detailed information on specific architectural concerns, refer to the following documentation:

| Topic                                            | Document                                                                                                                                                                                    |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authentication flows, tokens, and access control | [Authentication System Deep Dive](https://docs.flxbl.io/flxbl/sfp-server/architecture-overview/sfp-server-architecture-overview-beta/authentication-system-deep-dive)                       |
| Credential security and secret management        | [Authentication & Security Architecture](https://docs.flxbl.io/flxbl/sfp-server/architecture-overview/sfp-server-architecture-overview-beta/authentication-and-security-architecture)       |
| Network topology and external integrations       | [Network Architecture & Integration System](https://docs.flxbl.io/flxbl/sfp-server/architecture-overview/sfp-server-architecture-overview-beta/network-architecture-and-integration-system) |
| Database design and real-time state              | [Database Architecture](https://docs.flxbl.io/flxbl/sfp-server/architecture-overview/sfp-server-architecture-overview-beta/database-architecture)                                           |
| Task queues, workers, and execution model        | [Task Processing System](https://docs.flxbl.io/flxbl/sfp-server/architecture-overview/sfp-server-architecture-overview-beta/task-processing-system)                                         |

## System Requirements

Each organization's dedicated instance requires a modern cloud virtual machine (AWS EC2, Azure VM, or Hetzner Server) with a minimum of 8GB RAM, 4 vCPUs, and 80GB SSD storage for container and data volumes, plus a static IP address with direct internet connectivity.

The instance must have outbound access to Salesforce API endpoints, standard HTTP/HTTPS ports for external access, internal network isolation capabilities, and access to required authentication providers. Storage provisioning must account for database storage, Redis persistence, temporary processing files, and backup allocation.