Overview

RAGSpine's engine is ordinary Python: typed seams, dataclasses, explicit stores, and readable control flow. answer_question(...) is the Q&A composition entry point. A separate workflow domain parses, scaffolds, previews, converts, and compiles Dify-compatible configuration; an optional FastAPI service exposes those operations and a deliberately default-off executor.

This distinction matters. RAGSpine has Dify and n8n interchange surfaces, but it does not embed either platform's runtime, download their marketplaces at runtime, or require a graph framework to answer a question.

Architectural commitments

Q&A request lifecycle

question
  → deterministic security/intent screening
  → clarification gateway
  → optional service-edge FAQ short-circuit
  → structured | narrative | composite route
       structured: normalize → query fact store → found/not_found/unrecognized
       narrative: filter → retrieve/fuse → rerank/postprocess → cited generation
       composite: execute both evidence paths and merge
  → anti-fabrication/provenance checks
  → answer + sources

Optional history is inserted only into the final generation message sequence. It never changes the deterministic intent/security decision, the retrieval query, or what counts as evidence.

The narrative path can use metadata filters, per-library routing with RRF fusion, and store-level parent/window expansion. Citation fields remain those of the child hit; expanded text is separate generation context. A restricted child is removed before expansion.

Workflow lifecycle

description or JSON/YAML/TOML
  → normalize to JSON-compatible mapping
  → explicit template or catalog match
  → reuse safe Dify workflow | generate fixed start→llm→end graph
  → deterministic YAML/JSON + preview schema v1
  → optional analyze / convert / compile
  → explicit server-controlled execution gate (off by default)

The catalog is package data: 7 curated templates plus 993 generated descriptors. Upstream Dify/n8n URLs are research metadata only; no upstream workflow text or credentials are redistributed.

Trust boundaries

• The base library and catalog need no API key.
• The service's ordinary engine/catalog/compiler routes have no built-in application auth and must be protected by deployment infrastructure.
• Dify-compatible public endpoints require a Bearer app key; n8n-compatible public CRUD requires X-N8N-API-KEY.
• Webhooks are intentionally unauthenticated and need ingress controls.
• Workflow execution is additionally gated by RAGSPINE_DIFY_RUN_ENABLED=false by default.
• The in-process restriction layer is not an OS sandbox; subprocess resource limits are Linux-only.

Where to continue