Skip to main content

Architecture

Documentation Map​

Architecture

Version: 2026-04-01

System Overview​

Helpifyr Spool is a FastAPI-centered service stack with persisted metadata, object storage, vector retrieval, runtime support dependencies, and an optional orchestration and billing layer.

Core maintained deployment shape:

  • FastAPI application
  • PostgreSQL metadata store
  • MinIO artifact storage
  • Qdrant vector store
  • Redis runtime dependency
  • optional n8n orchestration
  • optional Paddle billing integration
  • optional Caddy TLS edge

Main Components​

  • app/api/main.py, app/api/health.py, app/webui.py
  • app/services/persistence.py
  • app/services/maintained_ingestion.py
  • scripts/ops/*

Data Flow​

  1. external source windows are requested through ingest endpoints
  2. maintained ingestion normalizes source records
  3. persistence writes metadata and artifacts to runtime stores
  4. search retrieves from persisted metadata and vector indexes
  5. snapshots/exports/research runs materialize reproducible downstream artifacts
  6. ops/release/readiness routes summarize runtime state

Interfaces​

Exposed:

  • maintained REST API under /v1/...
  • public docs under /docs and /redoc
  • metrics under /metrics

Consumed:

  • PostgreSQL
  • MinIO
  • Qdrant
  • Redis
  • external source providers
  • optional Paddle
  • optional n8n

Operating Assumptions​

  • Linux is the reference runtime and CI platform
  • compose.dev.yaml is the maintained deployment entrypoint
  • jhf-spool is the maintained stack name
  • the maintained contract is narrower than the historical repository surface

Helpifyr Ecosystem Role​

This repository is a supporting evidence service:

  • standalone-capable
  • useful to agents, governance tooling, and orchestration systems
  • not the central control plane itself

Expected Role Toward jhf-fabric (legacy alias: jhf-fabric)​

  • read-only discovery target
  • runtime/capability metadata provider
  • searchable evidence backend
  • not a Fabric-controlled deployment or mutation target

License: AGPLv3
Learn more: https://helpifyr.com