Package Layout

Current main contains 15 top-level domain packages under src/ragspine/ (excluding __pycache__). The layout is package-by-feature rather than a horizontal controllers/models/utils split.

src/ragspine/
├── agent/       intent, security, tool loop, provider seam, answer orchestration
├── cli/         installed ragspine command
├── common/      profile, glossary, sensitivity, observability, shared constants
├── dify/        Dify parser, IR, optimizer, code generation, restricted execution support
├── eval/        QA, extraction, retrieval, faithfulness, and regression gates
├── extraction/  Office/PDF/text extraction and StyledGrid IR
├── fixtures/    package fixtures used by demos/tests
├── graph/       provenance-aware structured/narrative relation graph seams
├── ingestion/   structured facts, narrative chunks, sources, manifests, review queue
├── n8n/         pure n8n ↔ Dify conversion
├── pipeline/    static engine topology values and Mermaid/DOT/JSON export
├── retrieval/   chunking, filtering, routing, lexical/vector search, rerank, postprocess
├── service/     FastAPI app, public compatibility APIs, queue, jobs, FAQ, config
├── storage/     fact-store protocol and SQLite implementation
└── workflows/   catalog, source policy, formats, matching, scaffold, preview v1

Responsibilities and boundaries

Engine core

common, storage, extraction, ingestion, retrieval, agent, graph, and eval implement the evidence path. Heavy SDKs are imported in adapters, not in the core seam definitions. A plain base install and MockProvider preserve the deterministic offline path.

retrieval now includes filtering/ for explicit metadata predicates and routing/ for multi-library selection/fusion. Parent-child/window data is stored in the chunk store so it survives restarts and can be expanded after a child hit without changing citation identity.

Workflow interoperability

workflows owns safe configuration ingestion and catalog/scaffold behavior. It is the only source of the preview-v1 display projection. dify owns Dify semantic parsing/IR/codegen. n8n converts between n8n JSON and Dify-shaped mappings with warnings and round-trip metadata.

These domains can prepare code or configuration, but do not implicitly execute it. Execution is a service concern with an explicit gate.

Edges

cli is the installed local edge. service is the network/composition edge and imports broadly to assemble resources. pipeline is a small static graph value/export layer for real engine topology; it is distinct from a workflow preview.

Two graph representations

Neither representation executes nodes.

Import and dependency rule of thumb

Domain code depends on small contracts and values; adapters depend inward on those contracts. service and cli are composition roots. New vendor SDKs belong in an optional adapter with a lazy import and conformance tests. Workflow clients must not bypass source policy, format limits, preview redaction, or the server execution gate.