# tg11-org/ff-pulse architecture

> Architecture diagram of the GitHub repository tg11-org/ff-pulse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tg11-org/ff-pulse
- Repository: https://github.com/tg11-org/ff-pulse

## Overview

Pulse is an asynchronous job execution engine: workers consume jobs from Redis, dispatch by job type, and invoke handlers that coordinate infrastructure operations with Fabric and state updates with Core. Its domain stages are provisioning, instance lifecycle changes, and state reconciliation; retry and terminal-job checks are orchestration concerns. The graph preserves the documented worker, queue, handler, integration, and metrics capabilities. Some worker and consumer details are excerpted only partially, so those relationships rely on the README or source-index references.

Main entry points: [`pulse/worker.py`](https://github.com/tg11-org/ff-pulse/blob/master/pulse/worker.py) (Worker pool), [`pulse/clients/core_api.py`](https://github.com/tg11-org/ff-pulse/blob/master/pulse/clients/core_api.py) (Core API client), [`pulse/clients/fabric_client.py`](https://github.com/tg11-org/ff-pulse/blob/master/pulse/clients/fabric_client.py) (Fabric client), [`pulse/config.py`](https://github.com/tg11-org/ff-pulse/blob/master/pulse/config.py) (Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Worker orchestration"]
  node_entrypoint["Service entry point<br/>[main.py]"]
  node_worker["Worker pool<br/>[worker.py]"]
  node_queue_consumer["Redis consumer<br/>[redis_consumer.py]"]
end

subgraph group_jobs["Job workflows"]
  node_provision["Provision handler<br/>[provision.py]"]
  node_lifecycle["Lifecycle handler<br/>[lifecycle.py]"]
  node_sync["State sync handler<br/>[sync.py]"]
end

subgraph group_integrations["External integrations"]
  node_redis["Redis queue"]
  node_core_client["Core API client<br/>[core_api.py]"]
  node_core_api["Core control plane"]
  node_fabric_client["Fabric client<br/>[fabric_client.py]"]
  node_fabric["Fabric infrastructure"]
end

subgraph group_operations["Operations"]
  node_config["Configuration<br/>[config.py]"]
  node_logging["Structured logging<br/>[logging.py]"]
  node_metrics["Job metrics<br/>[metrics.py]"]
end

node_operator(("Operator"))

node_operator -->|"starts"| node_entrypoint
node_entrypoint -->|"runs workers"| node_worker
node_entrypoint -->|"starts server"| node_metrics
node_entrypoint -->|"reads settings"| node_config
node_queue_consumer -->|"pops jobs"| node_redis
node_queue_consumer -->|"enqueues jobs"| node_redis
node_worker -->|"consumes jobs"| node_queue_consumer
node_worker -->|"dispatches"| node_provision
node_worker -->|"dispatches"| node_lifecycle
node_worker -->|"dispatches"| node_sync
node_worker -->|"checks job state"| node_core_client
node_worker -->|"records outcomes"| node_metrics
node_provision -->|"reads and updates"| node_core_client
node_provision -->|"creates instance"| node_fabric_client
node_lifecycle -->|"reads and updates"| node_core_client
node_lifecycle -->|"runs operation"| node_fabric_client
node_sync -->|"reads and updates"| node_core_client
node_sync -->|"queries status"| node_fabric_client
node_core_client -->|"calls API"| node_core_api
node_fabric_client -->|"calls API"| node_fabric
node_worker -->|"uses settings"| node_config
node_queue_consumer -->|"uses settings"| node_config
node_core_client -->|"uses settings"| node_config
node_fabric_client -->|"uses settings"| node_config

click node_entrypoint "https://github.com/tg11-org/ff-pulse/blob/master/pulse/main.py"
click node_worker "https://github.com/tg11-org/ff-pulse/blob/master/pulse/worker.py"
click node_queue_consumer "https://github.com/tg11-org/ff-pulse/blob/master/pulse/consumers/redis_consumer.py"
click node_provision "https://github.com/tg11-org/ff-pulse/blob/master/pulse/jobs/provision.py"
click node_lifecycle "https://github.com/tg11-org/ff-pulse/blob/master/pulse/jobs/lifecycle.py"
click node_sync "https://github.com/tg11-org/ff-pulse/blob/master/pulse/jobs/sync.py"
click node_core_client "https://github.com/tg11-org/ff-pulse/blob/master/pulse/clients/core_api.py"
click node_fabric_client "https://github.com/tg11-org/ff-pulse/blob/master/pulse/clients/fabric_client.py"
click node_config "https://github.com/tg11-org/ff-pulse/blob/master/pulse/config.py"
click node_logging "https://github.com/tg11-org/ff-pulse/blob/master/pulse/logging.py"
click node_metrics "https://github.com/tg11-org/ff-pulse/blob/master/pulse/metrics.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entrypoint,node_worker,node_queue_consumer toneBlue
class node_provision,node_lifecycle,node_sync toneAmber
class node_redis,node_core_client,node_core_api,node_fabric_client,node_fabric toneMint
class node_config,node_logging,node_metrics toneRose
class node_operator toneIndigo
```

## Components

### Worker orchestration

- [Service entry point](https://github.com/tg11-org/ff-pulse/blob/master/pulse/main.py): `pulse/main.py`
- [Worker pool](https://github.com/tg11-org/ff-pulse/blob/master/pulse/worker.py): `pulse/worker.py`
- [Redis consumer](https://github.com/tg11-org/ff-pulse/blob/master/pulse/consumers/redis_consumer.py): `pulse/consumers/redis_consumer.py`

### Job workflows

- [Provision handler](https://github.com/tg11-org/ff-pulse/blob/master/pulse/jobs/provision.py): `pulse/jobs/provision.py`
- [Lifecycle handler](https://github.com/tg11-org/ff-pulse/blob/master/pulse/jobs/lifecycle.py): `pulse/jobs/lifecycle.py`
- [State sync handler](https://github.com/tg11-org/ff-pulse/blob/master/pulse/jobs/sync.py): `pulse/jobs/sync.py`

### External integrations

- **Redis queue**
- [Core API client](https://github.com/tg11-org/ff-pulse/blob/master/pulse/clients/core_api.py): `pulse/clients/core_api.py`
- **Core control plane**
- [Fabric client](https://github.com/tg11-org/ff-pulse/blob/master/pulse/clients/fabric_client.py): `pulse/clients/fabric_client.py`
- **Fabric infrastructure**

### Operations

- [Configuration](https://github.com/tg11-org/ff-pulse/blob/master/pulse/config.py): `pulse/config.py`
- [Structured logging](https://github.com/tg11-org/ff-pulse/blob/master/pulse/logging.py): `pulse/logging.py`
- [Job metrics](https://github.com/tg11-org/ff-pulse/blob/master/pulse/metrics.py): `pulse/metrics.py`

### Other components

- **Operator**

## Connections

- Operator → Service entry point: starts (evidence: `README.md`)
- Service entry point → Worker pool: runs workers (evidence: `pulse/main.py`)
- Service entry point → Job metrics: starts server (evidence: `pulse/main.py`)
- Service entry point → Configuration: reads settings (evidence: `pulse/main.py`)
- Redis consumer → Redis queue: pops jobs (evidence: `pulse/consumers/redis_consumer.py`)
- Redis consumer → Redis queue: enqueues jobs (evidence: `pulse/consumers/redis_consumer.py`)
- Worker pool → Redis consumer: consumes jobs (evidence: `README.md`)
- Worker pool → Provision handler: dispatches (evidence: `pulse/worker.py`)
- Worker pool → Lifecycle handler: dispatches (evidence: `pulse/worker.py`)
- Worker pool → State sync handler: dispatches (evidence: `pulse/worker.py`)
- Worker pool → Core API client: checks job state (evidence: `pulse/worker.py`)
- Worker pool → Job metrics: records outcomes (evidence: `pulse/worker.py`)
- Provision handler → Core API client: reads and updates (evidence: `pulse/jobs/provision.py`)
- Provision handler → Fabric client: creates instance (evidence: `pulse/jobs/provision.py`)
- Lifecycle handler → Core API client: reads and updates (evidence: `pulse/jobs/lifecycle.py`)
- Lifecycle handler → Fabric client: runs operation (evidence: `pulse/jobs/lifecycle.py`)
- State sync handler → Core API client: reads and updates (evidence: `pulse/jobs/sync.py`)
- State sync handler → Fabric client: queries status (evidence: `pulse/jobs/sync.py`)
- Core API client → Core control plane: calls API (evidence: `pulse/clients/core_api.py`)
- Fabric client → Fabric infrastructure: calls API (evidence: `pulse/clients/fabric_client.py`)
- Worker pool → Configuration: uses settings (evidence: `pulse/worker.py`)
- Redis consumer → Configuration: uses settings (evidence: `pulse/consumers/redis_consumer.py`)
- Core API client → Configuration: uses settings (evidence: `pulse/clients/core_api.py`)
- Fabric client → Configuration: uses settings (evidence: `pulse/clients/fabric_client.py`)