Project Structure

As your AI application grows, organizing your project becomes essential for maintainability and scalability.

Ragfish does not enforce a specific directory structure, but following a consistent project layout makes it easier to manage assistants, knowledge sources, connectors, and application logic.

This guide presents the recommended project structure for most Ragfish applications.

Recommended Project Structure

A typical Ragfish project looks like this:

my-ragfish-app/
│
├── src/
│   ├── assistants/
│   ├── config/
│   ├── connectors/
│   ├── ingestion/
│   ├── retrievers/
│   ├── vectorstores/
│   ├── services/
│   ├── routes/
│   ├── utils/
│   └── index.ts
│
├── knowledge/
│   ├── documents/
│   ├── spreadsheets/
│   ├── pdfs/
│   └── images/
│
├── .env
├── package.json
├── tsconfig.json
└── README.md

This structure separates framework components from application-specific logic, making projects easier to understand and maintain.

Directory Overview

src/

The src directory contains all application source code.

src/

This includes configuration, assistants, connectors, retrievers, API routes, and other application logic.

assistants/

src/assistants/

Store AI assistant definitions here.

Each assistant should contain its own configuration, prompt instructions, retriever settings, and business logic.

Example:
assistants/
├── hr-assistant.ts
├── support-assistant.ts
└── compliance-assistant.ts

config/

src/config/

Contains application configuration.

Typical files include:

1. AI provider configuration

2. Environment variables

3. Framework settings

4. Application constants

connectors/

src/connectors/

Connectors import knowledge from external sources.

Examples include:

1. Spreadsheet Connector

2. PDF Connector

3. Database Connector

4. Website Connector

5. Documentation Connector

Each connector is responsible for loading and preparing data before ingestion.

ingestion/

src/ingestion/

The ingestion layer processes raw knowledge before it is stored.

Typical responsibilities include:

1. Loading documents

2. Text extraction

3. Metadata generation

4. Chunk creation

5. Embedding generation

retrievers/

src/retrievers/

Retrievers search the vector database and return relevant content for each query.

Different retrievers may implement different search strategies, such as:

1. Semantic Search

2. Hybrid Search

3. Metadata Filtering

4. Similarity Search

vectorstores/

src/vectorstores/

Contains vector database configuration.

Examples:

1. Qdrant

2. Chroma

3. Pinecone

4. Weaviate

Each implementation manages connections and collection configuration.

services/

src/services/

Contains business logic that is independent of Ragfish.

Examples:

1. User management

2. Authentication

3. Notifications

4. Reporting

5. Custom workflows

Keeping business logic separate from AI components improves maintainability.

routes/

src/routes/

Defines API endpoints for your application.

Examples:

GET /assistants

POST /ingest

POST /chat

This folder is optional but recommended for backend applications.

utils/

src/utils/

Shared utility functions.

Examples:

1. Date formatting

2. Validation

3. Logging

4. Helper functions

Knowledge Directory

knowledge/

This directory contains the raw knowledge sources used by your AI assistants.

Example:

knowledge/
├── documents/
├── pdfs/
├── spreadsheets/
└── images/

Depending on your application, these files may later be ingested into a vector database.

Configuration Files

.env

Stores environment variables.

Example:
OPENAI_API_KEY=your-api-key
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=your-api-key

Never commit this file to version control.

package.json

Defines project dependencies and scripts.

tsconfig.json

Contains the TypeScript compiler configuration.

Why This Structure?

This organization provides several benefits:

1. Clear separation of responsibilities

2. Easier maintenance

3. Better scalability

4. Reusable assistants

5. Independent connectors

6. Cleaner business logic

7. Improved team collaboration

As your application grows, each feature can evolve independently without affecting the rest of the project.

Example Workflow

A typical request flows through the project like this:

User Question
      │
      ▼
API Route
      │
      ▼
Assistant
      │
      ▼
Retriever
      │
      ▼
Vector Store
      │
      ▼
Language Model
      │
      ▼
Response

This layered architecture keeps the framework modular and easy to extend.

Best Practices

When building Ragfish applications:

1. Keep assistants focused on a single domain.

2. Store reusable configuration in the config directory.

3. Separate business logic from AI logic.

4. Organize knowledge sources by type.

5. Keep connectors independent and reusable.

6. Use environment variables for secrets and API keys.

7. Create separate retrievers when different search strategies are required.

Following these practices will make your application easier to test, maintain, and scale.

What's Next?

Now that you understand how to organize a Ragfish project, it's time to build your first AI assistant.

Continue to Your First AI Assistant, where you'll combine the concepts from this guide to create a complete AI-powered application using Ragfish.