# tg11-org/ff-fabric architecture

> Architecture diagram of the GitHub repository tg11-org/ff-fabric, 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-fabric
- Repository: https://github.com/tg11-org/ff-fabric

## Overview

Fabric presents infrastructure provisioning and lifecycle operations through a provider-neutral Python interface and an HTTP API intended for Pulse. The API validates requests, selects a configured or fake provider, and returns normalized results; the Proxmox implementation performs container/VM creation, lifecycle operations, template cloning, and asynchronous task polling through an authenticated REST client. Shared models and exceptions keep provider details behind the abstraction. The sampled sources show these core calls; other provider capabilities are documented by the README or interface but are not separately verified in excerpts.

Main entry points: [`fabric/providers/proxmox.py`](https://github.com/tg11-org/ff-fabric/blob/master/fabric/providers/proxmox.py) (Proxmox provider), [`fabric/api.py`](https://github.com/tg11-org/ff-fabric/blob/master/fabric/api.py) (HTTP endpoints), [`fabric/clients/proxmox_client.py`](https://github.com/tg11-org/ff-fabric/blob/master/fabric/clients/proxmox_client.py) (REST client), [`fabric/exceptions.py`](https://github.com/tg11-org/ff-fabric/blob/master/fabric/exceptions.py) (Domain errors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_http_api["HTTP endpoints<br/>[api.py]"]
  node_provider_select["Provider selection<br/>[api.py]"]
  node_api_models["API payloads<br/>[api.py]"]
end

subgraph group_domain["Fabric Contract"]
  node_fabric_models["Operation models<br/>[models.py]"]
  node_provider_interface["Provider interface<br/>[base.py]"]
  node_domain_errors["Domain errors<br/>[exceptions.py]"]
end

subgraph group_provider["Provider Operations"]
  node_proxmox_provider["Proxmox provider<br/>[proxmox.py]"]
  node_provision["VM and container creation<br/>[proxmox.py]"]
  node_lifecycle["Instance lifecycle<br/>[proxmox.py]"]
  node_clone_tasks["Clone and task handling<br/>[proxmox.py]"]
end

subgraph group_transport["Proxmox Transport"]
  node_proxmox_client["REST client<br/>[proxmox_client.py]"]
end

node_pulse(("Pulse client"))
node_proxmox["Proxmox API"]

node_pulse -->|"sends HTTP"| node_http_api
node_http_api -->|"selects provider"| node_provider_select
node_http_api -->|"validates payloads"| node_api_models
node_http_api -->|"builds requests"| node_fabric_models
node_http_api -->|"invokes operations"| node_proxmox_provider
node_provider_select -->|"constructs provider"| node_proxmox_provider
node_proxmox_provider -->|"implements contract"| node_provider_interface
node_proxmox_provider -->|"uses models"| node_fabric_models
node_proxmox_provider -->|"implements"| node_provision
node_proxmox_provider -->|"implements"| node_lifecycle
node_proxmox_provider -->|"implements"| node_clone_tasks
node_provision -->|"posts requests"| node_proxmox_client
node_lifecycle -->|"calls REST methods"| node_proxmox_client
node_clone_tasks -->|"polls tasks"| node_proxmox_client
node_proxmox_client -->|"sends REST requests"| node_proxmox
node_proxmox_client -->|"raises errors"| node_domain_errors
node_proxmox_provider -->|"raises operation errors"| node_domain_errors
node_http_api -->|"maps to HTTP errors"| node_domain_errors

click node_http_api "https://github.com/tg11-org/ff-fabric/blob/master/fabric/api.py"
click node_provider_select "https://github.com/tg11-org/ff-fabric/blob/master/fabric/api.py"
click node_api_models "https://github.com/tg11-org/ff-fabric/blob/master/fabric/api.py"
click node_fabric_models "https://github.com/tg11-org/ff-fabric/blob/master/fabric/models.py"
click node_provider_interface "https://github.com/tg11-org/ff-fabric/blob/master/fabric/base.py"
click node_domain_errors "https://github.com/tg11-org/ff-fabric/blob/master/fabric/exceptions.py"
click node_proxmox_provider "https://github.com/tg11-org/ff-fabric/blob/master/fabric/providers/proxmox.py"
click node_provision "https://github.com/tg11-org/ff-fabric/blob/master/fabric/providers/proxmox.py"
click node_lifecycle "https://github.com/tg11-org/ff-fabric/blob/master/fabric/providers/proxmox.py"
click node_clone_tasks "https://github.com/tg11-org/ff-fabric/blob/master/fabric/providers/proxmox.py"
click node_proxmox_client "https://github.com/tg11-org/ff-fabric/blob/master/fabric/clients/proxmox_client.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_http_api,node_provider_select,node_api_models,node_pulse toneBlue
class node_fabric_models,node_provider_interface,node_domain_errors toneAmber
class node_proxmox_provider,node_provision,node_lifecycle,node_clone_tasks,node_proxmox toneMint
class node_proxmox_client toneRose
```

## Components

### HTTP API

- [HTTP endpoints](https://github.com/tg11-org/ff-fabric/blob/master/fabric/api.py): `fabric/api.py`
- [Provider selection](https://github.com/tg11-org/ff-fabric/blob/master/fabric/api.py): `fabric/api.py`
- [API payloads](https://github.com/tg11-org/ff-fabric/blob/master/fabric/api.py): `fabric/api.py`

### Fabric Contract

- [Operation models](https://github.com/tg11-org/ff-fabric/blob/master/fabric/models.py): `fabric/models.py`
- [Provider interface](https://github.com/tg11-org/ff-fabric/blob/master/fabric/base.py): `fabric/base.py`
- [Domain errors](https://github.com/tg11-org/ff-fabric/blob/master/fabric/exceptions.py): `fabric/exceptions.py`

### Provider Operations

- [Proxmox provider](https://github.com/tg11-org/ff-fabric/blob/master/fabric/providers/proxmox.py): `fabric/providers/proxmox.py`
- [VM and container creation](https://github.com/tg11-org/ff-fabric/blob/master/fabric/providers/proxmox.py): `fabric/providers/proxmox.py`
- [Instance lifecycle](https://github.com/tg11-org/ff-fabric/blob/master/fabric/providers/proxmox.py): `fabric/providers/proxmox.py`
- [Clone and task handling](https://github.com/tg11-org/ff-fabric/blob/master/fabric/providers/proxmox.py): `fabric/providers/proxmox.py`

### Proxmox Transport

- [REST client](https://github.com/tg11-org/ff-fabric/blob/master/fabric/clients/proxmox_client.py): `fabric/clients/proxmox_client.py`

### Other components

- **Pulse client**
- **Proxmox API**

## Connections

- Pulse client → HTTP endpoints: sends HTTP (evidence: `fabric/api.py`)
- HTTP endpoints → Provider selection: selects provider (evidence: `fabric/api.py`)
- HTTP endpoints → API payloads: validates payloads (evidence: `fabric/api.py`)
- HTTP endpoints → Operation models: builds requests (evidence: `fabric/api.py`)
- HTTP endpoints → Proxmox provider: invokes operations (evidence: `fabric/api.py`)
- Provider selection → Proxmox provider: constructs provider (evidence: `fabric/api.py`)
- Proxmox provider → Provider interface: implements contract (evidence: `README.md`)
- Proxmox provider → Operation models: uses models (evidence: `fabric/providers/proxmox.py`)
- Proxmox provider → VM and container creation: implements (evidence: `fabric/providers/proxmox.py`)
- Proxmox provider → Instance lifecycle: implements (evidence: `fabric/providers/proxmox.py`)
- Proxmox provider → Clone and task handling: implements (evidence: `fabric/providers/proxmox.py`)
- VM and container creation → REST client: posts requests (evidence: `fabric/providers/proxmox.py`)
- Instance lifecycle → REST client: calls REST methods (evidence: `fabric/providers/proxmox.py`)
- Clone and task handling → REST client: polls tasks (evidence: `fabric/providers/proxmox.py`)
- REST client → Proxmox API: sends REST requests (evidence: `fabric/clients/proxmox_client.py`)
- REST client → Domain errors: raises errors (evidence: `fabric/clients/proxmox_client.py`)
- Proxmox provider → Domain errors: raises operation errors (evidence: `fabric/providers/proxmox.py`)
- HTTP endpoints → Domain errors: maps to HTTP errors (evidence: `fabric/api.py`)