How falkordb/queryweaver works
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