Architecture
The Ragfish Framework is designed around a modular architecture that transforms knowledge into intelligent conversations.
Instead of tightly coupling AI models, vector databases, and document processing, Ragfish separates each responsibility into independent components. This makes applications easier to understand, extend, and maintain.
This page explains how these components work together and how a user request flows through the framework.
High-Level Architecture
Every Ragfish application follows the same architecture.
Ragfish Framework
+----------------------+
| AI Assistant |
+----------+-----------+
|
▼
+----------------------+
| Chat |
+----------+-----------+
|
▼
+----------------------+
| Retriever |
+----------+-----------+
|
▼
+----------------------+
| Vector Store |
+----------+-----------+
▲
|
+----------------------+
| Embeddings |
+----------+-----------+
▲
|
+----------------------+
| Chunking |
+----------+-----------+
▲
|
+----------------------+
| Ingestion |
+----------+-----------+
▲
|
+----------------------+
| Knowledge Sources |
+----------------------+
Every layer has a single responsibility, allowing you to replace or extend individual components without affecting the rest of the application.
Framework Layers
Knowledge Sources
Knowledge is the foundation of every AI assistant.
Ragfish can ingest information from multiple sources, including:
PDF documents
Microsoft Excel spreadsheets
Websites
Technical documentation
Databases
Notion
SharePoint
Google Drive
Knowledge sources contain the information that your assistant will later retrieve and use to answer questions.
Ingestion
The ingestion layer imports knowledge into Ragfish.
Typical responsibilities include:
Loading documents
Extracting text
Reading metadata
Preparing content for processing
At this stage, the knowledge is still in its raw form.
Chunking
Large documents cannot be embedded efficiently as a single block.
The chunking layer divides documents into smaller, meaningful sections.
Example: Employee Handbook ↓ Introduction ↓ Leave Policy ↓ Work From Home Policy ↓ Travel Policy ↓ Benefits
These chunks become the searchable units stored in the vector database.
Embeddings
Each chunk is converted into a numerical vector using an embedding model.
Embeddings capture the semantic meaning of text, allowing similar content to be found even when different words are used.
For example:
"How many annual leave days do employees receive?"
can retrieve:
"Employees are entitled to twenty days of paid annual leave."
even though the wording is different.
Vector Store
Embeddings are stored inside a vector database.
Supported vector stores include:
Qdrant
Chroma (Coming Soon)
Pinecone (Coming Soon)
Weaviate (Coming Soon)
Milvus (Coming Soon)
The vector store enables fast semantic search across large knowledge bases.
Retrieval
When a user asks a question, the retriever searches the vector database and returns the most relevant chunks.
The retriever is responsible for:
Semantic search
Similarity ranking
Metadata filtering
Top-K retrieval
The retrieved content becomes the context sent to the language model.
Chat
The Chat component coordinates the conversation.
It is responsible for:
Receiving user messages
Invoking the retriever
Building prompts
Calling the language model
Returning responses
Most applications interact with the framework through the Chat API.
Assistant
An Assistant represents the complete AI application.
An assistant combines:
AI provider
Knowledge source
Retriever
Chat engine
Configuration
Instructions
For example:
HR Assistant
Product Documentation Assistant
Compliance Assistant
Customer Support Assistant
- Each assistant can have its own knowledge base and behavior while sharing the same framework.
Request Flow
The following diagram shows what happens when a user submits a question.
User │ ▼ Assistant │ ▼ Chat │ ▼ Retriever │ ▼ Vector Store │ ▼ Relevant Chunks │ ▼ Prompt Builder │ ▼ Large Language Model │ ▼ AI Response
The framework manages this workflow automatically.
Developers only need to configure the components.
Package Architecture
Ragfish is distributed as modular packages.
@ragfish/core
│
├── Settings
├── Assistant
├── Chat
├── Ingestion
├── Chunking
├── Retrieval
├── Interfaces
└── Types
@ragfish/openai
├── OpenAILLM
└── OpenAIEmbedding
@ragfish/qdrant
├── QdrantVectorStore
└── QdrantRetriever
@ragfish/spreadsheet
└── Spreadsheet Connector
This package structure allows developers to install only the integrations required by their applications.
Design Principles
The architecture of Ragfish is guided by four principles.
Separation of Responsibilities
Every component follows the same programming model and TypeScript conventions.
Consistency
Developers can build custom providers, connectors, retrievers, and vector stores.
Extensibility
Components can be replaced without changing the rest of the application.
Modularity
Each component focuses on a single task.
What's Next?
Now that you understand the overall architecture of Ragfish, the next step is to learn how the framework is configured.
Continue to Settings, where you'll learn how to configure AI providers, embedding models, and global framework options.