# falkordb/queryweaver architecture

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

- Interactive diagram: https://gitdiagram.com/falkordb/queryweaver
- Repository: https://github.com/falkordb/queryweaver

## Overview

##### Project type and purpose
- QueryWeaver is a full-stack web application.
- Backend: FastAPI (Python) providing REST and MCP HTTP endpoints.
- Frontend: TypeScript + Jinja2 templates (served by the backend).
- Core functionality: convert user natural-language questions into SQL (Text2SQL) via graph-powered schema understanding and LLM calls.

##### File structure
- Top level:
- api/ – FastAPI backend modules
- app/ – TypeScript frontend (static assets + Jinja2 templates)
- tests/ – unit and E2E tests (Playwright)
- Dockerfile, Makefile, Pipfile, workflows – CI/CD and deployment configuration
- api/ subfolders:
- routes/ – HTTP routes (auth, graphs, tokens, database)
- agents/ – “chain‐of‐agents” that perform analysis, relevancy filtering, follow-ups, formatting
- loaders/ – graph schema loaders (generic JSON, MySQL, PostgreSQL)
- memory/ – in-process memory/tooling (graphiti_tool)
- auth/ – OAuth handlers (Google, GitHub), user management
- app_factory.py, extensions.py – application factory and FastAPI extension registration
- config.py – environment and LLM configuration (Azure/OpenAI)
- app/ structure:
- templates/ – Jinja2 templates for pages/components
- ts/ – TypeScript modules for UI logic (chat, graphs, modals, etc.)

##### README for insights
- Describes REST endpoints (/graphs, /graphs/{id}/data, POST /graphs, POST /graphs/{id})
- Mentions optional MCP server surface or client usage
- OAuth flows, streaming via SSE (`|||FALKORDB_MESSAGE_BOUNDARY|||`)
- Tech stack: FastAPI, Uvicorn, Python 3.12+, Node.js, npm, Playwright, Docker, MCP protocol

a. Client (Browser) – UI rendered via Jinja2 + TypeScript, communicates over HTTPS
b. API Server – FastAPI/Uvicorn application
c. Authentication subsystem – OAuth providers (Google, GitHub), session cookies, API tokens
d. Agent pipeline – analysis_agent, relevancy_agent, follow_up_agent, response_formatter_agent
e. Loaders & Graph Store – MySQL/PostgreSQL loaders, graph_loader, base_loader, memory/graphiti_tool
f. LLM Service – Azure OpenAI or OpenAI endpoints
g. FalkorDB (optional) – external MCP server or internal graph database
h. Persistence layer – user/account DB (if any), token store
i. Tests & CI – shown separately (unit tests, E2E tests, GitHub Actions)

##### Relationships and data flows
- Browser → API Server:
- GET / (serves HTML/JS/CSS)
- AJAX/Fetch/WebSocket for chat sessions (streaming SSE)
- API Server ↔ OAuth Providers:
- Redirect flow for Google/GitHub OAuth → session cookie
- API Server → Agents pipeline → LLM Service:
- Streaming requests/responses for Text2SQL chain
- API Server → Loaders → Schema store:
- On graph upload or database introspection
- API Server → FalkorDB (MCP):
- If acting as MCP client or hosting MCP endpoints
- API Server ↔ Persistence:
- User, token, graph metadata storage (could be a relational store)
- Tests → API Server & Browser:
- Unit tests call modules directly
- E2E tests use Playwright to exercise UI and API

##### Architectural patterns & design principles
- MVC‐style separation: templates (view), API routes (controller), agents/loaders (model)
- “Chain of Responsibility” for agent pipeline
- Plugin pattern: loaders and memory modules swappable via base classes
- Streaming responses (SSE) for real‐time chat
- Optional microservice (MCP) interface for reuse in other contexts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser)"
        direction TB
        Assets["Static Assets (CSS, images, icons, fonts)"]:::frontend
        Templates["Jinja2 Templates"]:::frontend
        UILogic["TypeScript UI Logic"]:::frontend
    end

    %% API Server Layer
    subgraph "API Server (FastAPI/Uvicorn)" 
        direction TB
        EntryPoint["FastAPI EntryPoint"]:::backend
        AppFactory["app_factory.py"]:::backend
        Extensions["extensions.py"]:::backend
        Config["config.py (Env & LLM)"]:::backend
    end

    %% Routes
    subgraph "HTTP Routes"
        direction TB
        AuthRoute["routes/auth.py"]:::backend
        TokenRoute["routes/tokens.py"]:::backend
        GraphsRoute["routes/graphs.py"]:::backend
        DatabaseRoute["routes/database.py"]:::backend
    end

    %% Auth Subsystem
    subgraph "Authentication Subsystem"
        direction TB
        OAuthHandlers["oauth_handlers.py"]:::backend
        UserManagement["user_management.py"]:::backend
    end

    %% Agent Pipeline
    subgraph "Agent Pipeline"
        direction TB
        AnalysisAgent["analysis_agent.py"]:::backend
        RelevancyAgent["relevancy_agent.py"]:::backend
        FollowUpAgent["follow_up_agent.py"]:::backend
        ResponseFormatterAgent["response_formatter_agent.py"]:::backend
        AgentUtils["utils.py"]:::backend
    end

    %% Loaders & Graph Store
    subgraph "Loaders & Graph Store"
        direction TB
        BaseLoader["base_loader.py"]:::backend
        JSONLoader["graph_loader.py"]:::backend
        MySQLLoader["mysql_loader.py"]:::backend
        PostgresLoader["postgres_loader.py"]:::backend
        GraphitiTool["graphiti_tool.py"]:::backend
    end

    %% LLM Service
    LLMService(["Azure/OpenAI LLM Service"]):::external

    %% FalkorDB / MCP Interface
    MCPHandler["graph.py (MCP Server/Client)"]:::external

    %% Persistence Layer
    PersistenceDB(["User & Metadata DB"]):::datastore

    %% Tests & CI
    subgraph "Tests & CI"
        direction TB
        UnitTests["tests/ (Unit Tests)"]:::external
        E2ETests["tests/ (Playwright E2E)"]:::external
        CIWorkflows[".github/workflows/"]:::external
        BuildScripts["Makefile, Dockerfile"]:::external
    end

    %% Connections
    Assets -->|"serves HTML/CSS/JS"| EntryPoint
    Templates --> EntryPoint
    UILogic --> EntryPoint

    EntryPoint -->|calls| AppFactory
    AppFactory --> Extensions
    AppFactory --> Config

    EntryPoint -->|includes| AuthRoute
    EntryPoint --> TokenRoute
    EntryPoint --> GraphsRoute
    EntryPoint --> DatabaseRoute

    AuthRoute --> OAuthHandlers
    AuthRoute --> UserManagement
    TokenRoute --> UserManagement

    EntryPoint -->|invokes| AnalysisAgent
    AnalysisAgent --> RelevancyAgent
    RelevancyAgent --> FollowUpAgent
    FollowUpAgent --> ResponseFormatterAgent
    ResponseFormatterAgent -->|formats Text2SQL| EntryPoint
    AgentUtils --> AnalysisAgent
    AgentUtils --> RelevancyAgent
    AgentUtils --> FollowUpAgent
    AgentUtils --> ResponseFormatterAgent

    EntryPoint -->|loads schema| BaseLoader
    BaseLoader --> JSONLoader
    BaseLoader --> MySQLLoader
    BaseLoader --> PostgresLoader
    EntryPoint --> GraphitiTool

    EntryPoint -->|streams| LLMService
    EntryPoint -->|optional MCP HTTP| MCPHandler

    EntryPoint -->|reads/writes| PersistenceDB
    GraphsRoute --> PersistenceDB
    DatabaseRoute --> PersistenceDB

    UnitTests -->|direct calls| EntryPoint
    E2ETests -->|exercises UI & API| EntryPoint
    E2ETests -->|exercises UI| Assets
    CIWorkflows --> UnitTests
    CIWorkflows --> E2ETests
    BuildScripts --> EntryPoint

    %% Click Events
    click Assets "https://github.com/falkordb/queryweaver/tree/main/app/public/"
    click Templates "https://github.com/falkordb/queryweaver/tree/main/app/templates/"
    click UILogic "https://github.com/falkordb/queryweaver/tree/main/app/ts/"
    click AppFactory "https://github.com/falkordb/queryweaver/blob/main/api/app_factory.py"
    click EntryPoint "https://github.com/falkordb/queryweaver/blob/main/api/index.py"
    click Extensions "https://github.com/falkordb/queryweaver/blob/main/api/extensions.py"
    click Config "https://github.com/falkordb/queryweaver/blob/main/api/config.py"
    click OAuthHandlers "https://github.com/falkordb/queryweaver/blob/main/api/auth/oauth_handlers.py"
    click UserManagement "https://github.com/falkordb/queryweaver/blob/main/api/auth/user_management.py"
    click AuthRoute "https://github.com/falkordb/queryweaver/blob/main/api/routes/auth.py"
    click TokenRoute "https://github.com/falkordb/queryweaver/blob/main/api/routes/tokens.py"
    click AnalysisAgent "https://github.com/falkordb/queryweaver/blob/main/api/agents/analysis_agent.py"
    click RelevancyAgent "https://github.com/falkordb/queryweaver/blob/main/api/agents/relevancy_agent.py"
    click FollowUpAgent "https://github.com/falkordb/queryweaver/blob/main/api/agents/follow_up_agent.py"
    click ResponseFormatterAgent "https://github.com/falkordb/queryweaver/blob/main/api/agents/response_formatter_agent.py"
    click AgentUtils "https://github.com/falkordb/queryweaver/blob/main/api/agents/utils.py"
    click BaseLoader "https://github.com/falkordb/queryweaver/blob/main/api/loaders/base_loader.py"
    click JSONLoader "https://github.com/falkordb/queryweaver/blob/main/api/loaders/graph_loader.py"
    click MySQLLoader "https://github.com/falkordb/queryweaver/blob/main/api/loaders/mysql_loader.py"
    click PostgresLoader "https://github.com/falkordb/queryweaver/blob/main/api/loaders/postgres_loader.py"
    click GraphitiTool "https://github.com/falkordb/queryweaver/blob/main/api/memory/graphiti_tool.py"
    click GraphsRoute "https://github.com/falkordb/queryweaver/blob/main/api/routes/graphs.py"
    click DatabaseRoute "https://github.com/falkordb/queryweaver/blob/main/api/routes/database.py"
    click MCPHandler "https://github.com/falkordb/queryweaver/blob/main/api/graph.py"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,color:#000
    classDef backend fill:#90EE90,stroke:#000,color:#000
    classDef external fill:#FFA500,stroke:#000,color:#000
    classDef datastore fill:#9370DB,stroke:#000,color:#000
```
