# rashadphz/farfalle architecture

> Architecture diagram of the GitHub repository rashadphz/farfalle, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rashadphz/farfalle
- Repository: https://github.com/rashadphz/farfalle

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        FE["Frontend (Next.js)"]:::frontend
    end

    subgraph "Backend Layer"
        BE["Backend (FastAPI)"]:::backend
        
        subgraph "Chat Module Details"
            CHAT["Chat Module"]:::module
            CHAT_IN["Input Processor"]:::module
            CHAT_RESP["Response Generator"]:::module
            CHAT --> CHAT_IN
            CHAT --> CHAT_RESP
        end
        
        subgraph "Agent Search Module Details"
            AGENT["Agent Search Module"]:::module
            AGENT_ROUTER["Query Router"]:::module
            AGENT_AGGR["Provider Aggregator"]:::module
            AGENT --> AGENT_ROUTER
            AGENT --> AGENT_AGGR
        end
        
        LLM["LLM Integration Module"]:::module
        STREAM["Streaming Module"]:::module
        
        BE --> CHAT
        BE --> AGENT
        BE --> LLM
        BE --> STREAM
    end

    subgraph "Search Providers"
        BING["Bing Provider"]:::provider
        SEARXNG["SearXNG Provider"]:::provider
        SERPER["Serper Provider"]:::provider
        TAVILY["Tavily Provider"]:::provider
    end

    EXTLLM["External LLM Services"]:::external
    DB(("Database (PostgreSQL)")):::database
    REDIS["Redis (Rate Limiter)"]:::aux

    subgraph "Deployment Tools"
        FDocker["Frontend Dockerfile"]:::deploy
        BDocker["Backend Dockerfile"]:::deploy
        COMPOSE["docker-compose.dev.yaml"]:::deploy
        SCRIPTS["docker-scripts"]:::deploy
    end

    MIG["Migrations (Alembic)"]:::database

    %% Flow Connections
    FE -->|"HTTP_Request"| BE
    AGENT_AGGR -->|"Coordinates"| BING
    AGENT_AGGR -->|"Coordinates"| SEARXNG
    AGENT_AGGR -->|"Coordinates"| SERPER
    AGENT_AGGR -->|"Coordinates"| TAVILY
    LLM -->|"LLM_Calls"| EXTLLM
    STREAM -->|"Streams Data"| EXTLLM
    BE -->|"DB_Ops"| DB
    BE -->|"RateLimit"| REDIS
    BE -->|"Migrate_DB"| MIG

    FDocker --> FE
    BDocker --> BE
    COMPOSE -- "dotted" --> FDocker
    COMPOSE -- "dotted" --> BDocker
    SCRIPTS -- "dotted" --> COMPOSE

    %% Click Events
    click FE "https://github.com/rashadphz/farfalle/tree/main/src/frontend"
    click BE "https://github.com/rashadphz/farfalle/tree/main/src/backend"
    click CHAT "https://github.com/rashadphz/farfalle/blob/main/src/backend/chat.py"
    click AGENT "https://github.com/rashadphz/farfalle/blob/main/src/backend/agent_search.py"
    click LLM "https://github.com/rashadphz/farfalle/tree/main/src/backend/llm"
    click STREAM "https://github.com/rashadphz/farfalle/blob/main/src/backend/streaming.py"
    click BING "https://github.com/rashadphz/farfalle/blob/main/src/backend/search/providers/bing.py"
    click SEARXNG "https://github.com/rashadphz/farfalle/blob/main/src/backend/search/providers/searxng.py"
    click SERPER "https://github.com/rashadphz/farfalle/blob/main/src/backend/search/providers/serper.py"
    click TAVILY "https://github.com/rashadphz/farfalle/blob/main/src/backend/search/providers/tavily.py"
    click DB "https://github.com/rashadphz/farfalle/tree/main/src/backend/db"
    click MIG "https://github.com/rashadphz/farfalle/tree/main/src/backend/alembic"
    click FDocker "https://github.com/rashadphz/farfalle/tree/main/src/frontend/Dockerfile"
    click BDocker "https://github.com/rashadphz/farfalle/tree/main/src/backend/Dockerfile"
    click COMPOSE "https://github.com/rashadphz/farfalle/blob/main/docker-compose.dev.yaml"
    click SCRIPTS "https://github.com/rashadphz/farfalle/tree/main/docker-scripts"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef backend fill:#C6F6D5,stroke:#333,stroke-width:2px;
    classDef module fill:#FCEBB6,stroke:#333,stroke-width:2px;
    classDef provider fill:#F8D3D3,stroke:#333,stroke-width:2px;
    classDef external fill:#FAD4AA,stroke:#333,stroke-width:2px;
    classDef database fill:#E2E8F0,stroke:#333,stroke-width:2px;
    classDef aux fill:#FFEDCC,stroke:#333,stroke-width:2px;
    classDef deploy fill:#E0BBE4,stroke:#333,stroke-width:2px;
```
