Skip to content

Commit 51ddf58

Browse files
gkorlandclaude
gkorland
and
claude
authored
docs: add AGENTS.md project guide and CLAUDE.md symlink (#477)
Provide a single-file onboarding reference covering architecture, tech stack, directory layout, build/test/lint commands, code conventions, environment variables, and CI/CD workflows. CLAUDE.md symlinks to AGENTS.md so both AI coding assistants and contributors find the same guide. Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 88dcc75 commit 51ddf58

2 files changed

Lines changed: 148 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# AGENTS.md — QueryWeaver (Text2SQL)
2+
3+
## Project Overview
4+
5+
QueryWeaver is an open-source Text2SQL tool that converts natural-language questions into SQL using graph-powered schema understanding backed by FalkorDB. It is a full-stack monorepo with a Python/FastAPI backend (`api/`) and a React/TypeScript frontend (`app/`).
6+
7+
Repository: `FalkorDB/QueryWeaver`
8+
9+
## Tech Stack
10+
11+
| Layer | Technology |
12+
|-------|-----------|
13+
| Backend | Python 3.12+, FastAPI, Uvicorn |
14+
| Frontend | React 18, TypeScript 5.8, Vite 7, Tailwind CSS |
15+
| Graph DB | FalkorDB |
16+
| LLM | LiteLLM (multi-provider: OpenAI, Gemini, Anthropic, Cohere, Azure, Ollama) |
17+
| Auth | OAuth 2.0 (Google, GitHub) via authlib |
18+
| Package mgmt | uv (Python), npm (Node) |
19+
| Testing | pytest (unit), Playwright (E2E) |
20+
| Linting | pylint (Python), ESLint (TypeScript) |
21+
| CI/CD | GitHub Actions |
22+
23+
## Directory Structure
24+
25+
```
26+
api/ Python backend (FastAPI)
27+
agents/ AI agents (analysis, healing, relevancy, follow-up)
28+
analyzers/ Code/syntax analyzers
29+
auth/ OAuth handlers, user management
30+
core/ Core text2sql logic, schema loading, errors
31+
entities/ Data models / DTOs
32+
loaders/ Database loaders (PostgreSQL, MySQL)
33+
memory/ Conversation memory management
34+
routes/ API endpoints (auth, graphs, database, tokens, settings)
35+
sql_utils/ SQL sanitization
36+
config.py LLM provider detection, configuration
37+
app_factory.py FastAPI app init, middleware
38+
index.py Application entry point
39+
app/ React + Vite frontend
40+
src/components/ React components
41+
src/contexts/ React contexts (Auth, Chat, Database, Settings)
42+
src/services/ API service layer
43+
src/types/ TypeScript type definitions
44+
tests/ Unit tests (pytest)
45+
e2e/ End-to-end tests (Playwright)
46+
docs/ Documentation
47+
.github/workflows/ CI/CD pipelines
48+
```
49+
50+
## Quick Reference
51+
52+
### Install & Setup
53+
54+
```bash
55+
make install # uv sync + npm ci
56+
make setup-dev # install + Playwright browsers
57+
cp .env.example .env # configure environment
58+
```
59+
60+
### Run
61+
62+
```bash
63+
make run-dev # dev server with hot reload (localhost:5000)
64+
make run-prod # production server
65+
make docker-falkordb # start FalkorDB in Docker
66+
```
67+
68+
### Test
69+
70+
```bash
71+
make test-unit # pytest unit tests
72+
make test-e2e # Playwright E2E (headless)
73+
make test-e2e-headed # Playwright E2E (visible browser)
74+
make test # build + unit + E2E
75+
```
76+
77+
### Lint
78+
79+
```bash
80+
make lint # pylint + ESLint
81+
make lint-frontend # ESLint only
82+
```
83+
84+
### Build
85+
86+
```bash
87+
make build-dev # Vite dev build
88+
make build-prod # Vite production build
89+
```
90+
91+
## Code Conventions
92+
93+
### Python (backend)
94+
95+
- PEP 8 with **120-char line limit**
96+
- Type hints throughout
97+
- pylint for linting (docstring checks disabled)
98+
- FastAPI routers split by domain under `api/routes/`
99+
- Custom exceptions in `api/core/errors.py` (GraphNotFoundError, InternalError, InvalidArgumentError)
100+
- Middleware: CSRF (double-submit cookies), HSTS headers
101+
- Environment config via dotenv; see `api/config.py` for defaults and provider detection
102+
- Run backend: `uv run uvicorn api.index:app`
103+
104+
### TypeScript / React (frontend)
105+
106+
- Strict TypeScript
107+
- ESLint with `@typescript-eslint`; unused vars prefixed with `_` are allowed
108+
- State management via React Context API
109+
- API calls through service layer (`app/src/services/`)
110+
- Styling with Tailwind CSS + Radix UI primitives
111+
- Routing with React Router v7
112+
- Forms with React Hook Form + Zod validation
113+
- Build tool: Vite (dev proxy to backend on port 5000)
114+
115+
### Testing
116+
117+
- **Unit tests** (`tests/`): pytest with markers `e2e`, `slow`, `auth`, `integration`, `unit`
118+
- **E2E tests** (`e2e/`): Playwright with Page Object Model pattern; auth setup runs first
119+
- E2E infra lives in `e2e/infra/`, page objects in `e2e/logic/pom/`
120+
- Test data (SQL init scripts) in `e2e/test-data/`
121+
122+
## Environment Variables
123+
124+
Required:
125+
- `FASTAPI_SECRET_KEY` — session secret
126+
- `FALKORDB_URL` — FalkorDB connection string (e.g. `redis://localhost:6379/0`)
127+
128+
LLM provider (set one): `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ANTHROPIC_API_KEY`, `COHERE_API_KEY`, `AZURE_API_KEY`, or `OLLAMA_MODEL`
129+
130+
Optional overrides: `COMPLETION_MODEL`, `EMBEDDING_MODEL` (must match provider)
131+
132+
See `.env.example` for the full list.
133+
134+
## CI/CD
135+
136+
GitHub Actions workflows (`.github/workflows/`):
137+
- **tests.yml** — unit tests + lint on push/PR to main/staging
138+
- **playwright.yml** — dedicated Playwright E2E suite
139+
- **pylint.yml** — Python linting
140+
- **spellcheck.yml** — docs spellcheck
141+
- **publish-docker.yml** — build & push Docker image to DockerHub
142+
- **dependency-review.yml** — dependency security review
143+
144+
## Branching
145+
146+
- `main` — production branch, target for PRs
147+
- `staging` — integration branch

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

0 commit comments

Comments
 (0)