Skip to content
Factflow

factflow-server

The FastAPI application, 91 API endpoints across 14 domains, service container, chat service, webhook service, and the factflow_server CLI entry point (embedded mode, serve mode).

Tier and role

Section titled “Tier and role”

Users don’t import factflow_server into other code; they run it (python -m factflow_server serve …) or call its HTTP endpoints via the CLI / API / frontend.

Context

Section titled “Context”

Seven responsibilities, one package:

  1. FastAPI app construction (main.create_app) — mounts every API router, middleware, CORS
  2. Startup / lifespan (startup.lifespan) — loads config, constructs service container, validates shipped YAMLs, starts orchestrator manager
  3. Service container (container.ServiceContainer) — dependency injection registry; every API route gets its services via Depends(get_container)
  4. API routers (api/v1/*.py) — one file per domain: system, configs, executions, pipelines, storage, lineage, search, replay, indexes, templates, adapters, chat, content, webhooks
  5. Chat service (chat/) — RAG-backed chat endpoints with multi-model search
  6. Webhook service (webhooks/) — subscription storage, delivery worker, retry + dead-letter
  7. Embedded mode (embedded.py) — boots a test-grade stack (embedded PostgreSQL, in-process queue) for factflow_server serve --embedded

Public API

Section titled “Public API”

Top-level re-exports are deliberately tiny:

from factflow_server import __version__

The server is a runnable, not a library. Routers and internal services are not part of the public contract. Tests and the CLI touch internals directly when necessary, but external integrations should go through HTTP.

CLI entry points

Section titled “CLI entry points”
python -m factflow_server serve           # full production-style serve
python -m factflow_server serve --embedded  # auto-Docker backend (local dev)

See backend/packages/factflow-server/src/factflow_server/__main__.py for flag details.

API endpoints

Section titled “API endpoints”

91 endpoints across 14 tags. Canonical reference: the running server’s /openapi.json (or generated openapi.toon at /openapi.toon). The docsite will auto-generate per-endpoint pages via starlight-openapi from a committed snapshot.

Tag → file mapping:

TagRouter file
adaptersapi/v1/adapters.py
chatapi/v1/chat.py
configsapi/v1/configs.py
contentapi/v1/content.py
embeddingsapi/v1/embeddings.py
executionsapi/v1/executions.py
indexesapi/v1/indexes.py
lineageapi/v1/lineage.py
pipelinesapi/v1/pipelines.py
replayapi/v1/replay.py
searchapi/v1/search.py
storageapi/v1/storage.py
systemapi/v1/system.py + api/v1/system_diagnostic.py
webhooksapi/v1/webhooks.py

Chat subpackage

Section titled “Chat subpackage”

factflow_server.chat exposes:

  • Multi-model search (RRF, hybrid, semantic)
  • Chat threads, sources, capabilities
  • Transient and persistent chat stores

All surfaced via /api/v1/chat/* endpoints.

Webhooks subpackage

Section titled “Webhooks subpackage”

factflow_server.webhooks — subscription CRUD, a delivery worker that consumes storage events and dispatches to HTTP targets, retry + dead-letter backoff.

Dependencies

Section titled “Dependencies”
  • Runtime: fastapi, uvicorn, pydantic, pydantic-settings, plus every other factflow-* package
  • Workspace: factflow-protocols, factflow-foundation, factflow-llm, factflow-infra, factflow-lineage, factflow-engine, factflow-execution + every workflow package (for adapter discovery)
  • External services: PostgreSQL (pgvector) + one queue broker + one storage backend

Testing

Section titled “Testing”

Tests at backend/packages/factflow-server/tests/ — API-level tests using FastAPI’s TestClient, end-to-end tests using Testcontainers for a real stack. See .claude/skills/backend/api-testing/ for patterns.

Section titled “Related”