Overview

Factflow’s backend is a uv workspace of 16 Python packages. This page is the map — pick a tier, pick a package, read its reference.

For deeper context on how packages relate at runtime see Architecture / Package map.

Tier map

Expand

flowchart TB
subgraph Workflows["WORKFLOWS (8)"]
  WS[factflow-webscraper]
  MD[factflow-markdown]
  EM[factflow-embeddings]
  BO[factflow-boost]
  TR[factflow-translator]
  KN[factflow-knowledge]
  SP[factflow-sharepoint]
  RP[factflow-replay]
end
subgraph Shared["SHARED SERVICES (7)"]
  FN[factflow-foundation]
  LIN[factflow-lineage]
  LLM[factflow-llm]
  INF[factflow-infra]
  EN[factflow-engine]
  EX[factflow-execution]
  SRV[factflow-server]
end
subgraph Core["CORE PROTOCOLS (1)"]
  PR[factflow-protocols]
end
Workflows --> Shared
Shared --> Core

Strict tiering. No reverse imports, no cross-workflow imports.

Core

One package, zero workspace dependencies. Every other package implements one or more of its contracts.

• factflow-protocols — PipelineAdapter, QueueProtocol, StorageProtocol, LLM protocols, plus supporting types and error classes.

Shared services

The services the server needs to run a pipeline.

• factflow-foundation — config framework, paths, correlation + observability
• factflow-lineage — lineage service, repository, PipelineLineageEntry model
• factflow-llm — LLM + embedding client factory, AIMD rate limiter, error classification
• factflow-infra — queue providers (Artemis / RabbitMQ / Pulsar) + storage providers (filesystem / MinIO)
• factflow-engine — orchestrator, processor, registry, backpressure, circuit breaker
• factflow-execution — execution lifecycle + ExecutionScopedQueue + DAG view
• factflow-server — FastAPI app, 91-endpoint HTTP surface, chat, webhooks

Workflow packages

Each is an independent feature package — its own adapters, its own domain. Workflows don’t import each other.

• factflow-webscraper — web scraping, sitemap parsing, adaptive rate limiting, JS-rendered crawler
• factflow-markdown — HTML → markdown → token-aware segments → storage
• factflow-embeddings — vector generation + repositories for search
• factflow-boost — Boost.AI chatbot export ingestion + catalogue
• factflow-translator — LLM-based translation with markdown preservation
• factflow-knowledge — concept detection, consolidation, knowledge diff
• factflow-sharepoint — SharePoint ingest via Microsoft Graph + document conversion
• factflow-replay — storage replay + recovery workflows

What you actually import

In decreasing order of frequency:

1. Adapter authors — factflow_protocols for PipelineAdapter, the contract, the types. Plus their own workflow package.
2. Test authors — the relevant workflow package plus factflow_engine.testing for the pipeline harness.
3. Protocol extenders — factflow_protocols plus the provider factory in factflow_infra / factflow_llm.
4. Server maintainers — anywhere in the stack.

Plain operators (write YAML + run factflow config run) import nothing.

Related

• Architecture / Package map — the dependency graph in detail
• Writing a new adapter — what to import when building a new workflow
• Extension points — every protocol you can implement