How rashadphz/farfalle works
Main Components
• Frontend: Located in src/frontend, this is built with Next.js and is responsible for rendering the user interface, handling search queries, and displaying results. It includes state management, UI components, and generated code (OpenAPI integration) to communicate with the backend.
• Backend: Located in src/backend. This is a FastAPI application that handles API requests, orchestrates search query processing, communicates with various search providers, and manages interactions with language models. It includes several modules (agent_search, chat, llm, search providers, and validators) and database configurations.
• Search Providers: Within src/backend/search/providers, there are individual modules for different providers (bing, searxng, serper, tavily) that encapsulate the logic for interacting with external search API endpoints.
• Database & ORM: Inside src/backend/db, the database models and engine are defined. A migration system is set up using Alembic (files under src/backend/alembic) to manage schema changes.
• External Services/Integrations:
• Local LLMs (llama3, mistral, gemma, phi3) and custom integration via LiteLLM.
• External APIs for search (as mentioned in README) – these integrations can be visualized as connectors from the backend.
• Auxiliary Components:
• Docker-related files and scripts (in docker-compose.dev.yaml, docker-scripts, Dockerfiles) indicating that container orchestration is a key part of the deployment pipeline.
• Rate limiting and logging components mentioned in the README (e.g., Redis and Logfire, even if their implementation is not deeply visible from the file tree, consider them part of the infrastructure).
Relationships and Data Flows
• The frontend submits search or chat requests to the backend via HTTP APIs.
• The backend receives these requests and may:
a. Directly query one or several search providers (using the modules under src/backend/search/providers).
b. Route the requests to internal services that integrate with local or external LLMs.
c. Use the database for storing chat history or user data as needed.
• Data flows include:
• Inter-component communication within the backend (e.g., the agent_search module coordinating among search providers and the llm module).
Architectural Patterns and Design Principles
• Separation of Concerns: Clear division between frontend and backend modules.
• Modularity: Each search provider is separated in its own module, allowing the easy addition or removal of providers.
• Containerization: With Docker and deployment scripts, the design supports consistent and reproducible environments for both development and production.
• API-First Approach: The use of auto-generated OpenAPI clients (within src/frontend/generated) from the backend API displays a tightly coupled and self-documented interaction protocol.
• Database Schema Migrations: Alembic is used to manage schema changes, ensuring that the persistence layer is reliably versioned and maintained.
Relevant Technologies and Frameworks
• Frontend: Next.js, Tailwind CSS, TypeScript.
• Backend: FastAPI, Redis (for rate limiting), Alembic (for DB migrations), and UWSGI (indicated by the presence of uwsgi.ini).
• Docker for containerization and orchestration, with separate Dockerfiles found in both frontend and backend directories.
• External APIs for search and LLM integration (Tavily, Serper, Bing, OpenAI, Groq, etc.)
Recommended Elements
• Clearly labeled components:
• “Frontend (Next.js)” with UI modules and state management.
• “Backend (FastAPI)” with sub-modules: Chat, Search, LLM, DB, and Agent Search.
• “Search Providers” as a consolidated section comprising individual providers (Bing, SearXNG, Serper, Tavily).
• “Database” (with migration system via Alembic) and potentially “Redis” for rate limiting.
• “External LLM Services” indicating both local and cloud-based models.
• Frontend → Backend for API requests.
• Backend → Search Providers for external search queries.
• Backend → LLM Integrations for processing responses.
• Additional annotations:
• Docker and CI/CD aspects from the .github workflows and docker-compose files.
• Decoupled nature of search provider integrations, which allow for easy modular updates.