Walkthroughs
Architecture explains the reusable system. These walkthroughs apply it to a fictional Atlas request and a separate operator-triggered knowledge update.
View source
How this step works
System map focus
View source
How this step works
Ingestion path
Manual ingestion
Select a node to explore its connections.
View all component details
- Selected sources: Select original versions and preserve their bytes, dates and provenance. For a rebuild, include the complete desired source set. For additions, prepare a delta and assemble it with the retained complete corpus before import.
- Conversion: Docling converts supported binary documents; supported text and JSON inputs use direct readers. Originals are mounted read only.
- Preparation: Normalize deterministically, preserve headings and substantive meaning, and record coverage, stable chunk IDs, hashes and offsets. No LLM summaries or rewriting.
- Embedding: Encode document chunks with shared BGE. Preserve configuration and vectors. Bound batch load so interactive queries retain capacity. For additions, assemble the embedded delta with the retained bundle before import.
- Import + verify: Import the complete bundle into a fresh Qdrant collection, independently verify identities and counts, after taking database backups. Import alone does not activate the running service.
- Activate Retrieval: The current private deployment requires an explicit local release-pin overlay and recreation of only Retrieval. Pointer-following installations use current or a GCS pointer. GCS cutover is pending. Database backups and matching prepared documents are recorded before the update.
The manual ingestion path for prepared text into the retrieval service.
Open the request-path reference diagram
Request path
Select a node to explore its connections.
View all component details
- Client: The client sends a question and an optional UUID conversation identifier to the shared entrance. It renders the answer returned by the operation and passes the UUID along for follow-up requests.
- MCP entrance: The MCP entrance receives client requests and forwards them through the LiteLLM gateway into the embedded FastMCP adapter, with a documented direct option available. It returns shared-operation results to the client. The entrance does not select models or execute the LangGraph application flow.
- NIS / LangGraph: The NIS orchestration node receives forwarded requests inside the Coordination service. It runs the shared operational flow, the incumbent model selector, and the LangGraph runtime to produce responses. The node returns grounded answers while delegating knowledge retrieval to the separate Retrieval MCP service.
- Retrieval MCP: The Retrieval MCP receives bounded search and read calls during the coordination flow. It queries BGE for vector encoding, executes hybrid search against Qdrant, and reads full text from the prepared document store. The service returns passages and document text but excludes all ingestion activities.
- Answer + thread_id: The answer node receives the completed operation result from the Coordination service. The client renders this plain response for the user; the node itself carries the answer data and thread_id back to the requester.
- PostgreSQL: PostgreSQL receives checkpoint writes from the LangGraph runtime during operations. It persists conversation state and lifecycle data across MCP transport sessions, enabling thread continuity. The database maintains these checkpoints independently from the prepared document knowledge used for retrieval.
- Inference provider: The inference provider receives the question and bounded grounding context assembled by the coordination flow. It generates responses using Ollama Cloud or Fireworks models according to the incumbent selector. The provider returns generated output for the answer path but does not perform retrieval.
- BGE server: The BGE server receives retrieval queries in query mode during search operations. It encodes these queries into vector embeddings used by the retrieval service. The service returns query embeddings to the retrieval flow; it does not read full documents or generate final answers.
- Prepared text: The prepared text store receives document identifiers selected by the search process. It serves the full prepared document text for those specific identifiers. The store returns document content for grounding context while remaining separate from conversion and import workflows. Reads occur when content is needed.
- Grounding evidence: The grounding evidence node receives Qdrant passages and prepared document text gathered during retrieval. It packages this bounded context for the inference provider. The node returns grounding material attached to the question; no manual ingestion is triggered during this question flow.
- Qdrant search: Qdrant receives vector embeddings produced by the BGE server. It performs dense and lexical hybrid search over the active prepared release to identify relevant content. The index returns matching passages and chunk identifiers; it operates separately from conversation checkpoints.
The shared request operation, including MCP access, retrieval, and inference.