Skip to content

Commit 97b6113

Browse files
gkorlandgkorland
authored
Merge pull request #613 from FalkorDB/async-endpoints
docs: sync docs with current FastAPI implementation
2 parents 0c64e8d + e99d718 commit 97b6113

2 files changed

Lines changed: 144 additions & 105 deletions

File tree

‎.env.template‎

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,28 @@
22
FALKORDB_HOST=localhost
33
FALKORDB_PORT=6379
44

5-
# OpenAI API key for LLM features
6-
OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
5+
# Optional FalkorDB authentication
6+
FALKORDB_USERNAME=
7+
FALKORDB_PASSWORD=
78

8-
# Secret token for API authentication
9+
# Token checked by authenticated endpoints. If left empty, the current
10+
# implementation accepts requests without an Authorization header.
911
SECRET_TOKEN=<YOUR_SECRET_TOKEN>
1012

11-
# Flask server settings
12-
FLASK_RUN_HOST=0.0.0.0
13-
FLASK_RUN_PORT=5000
14-
15-
# Set to 1 to enable public access for analyze_repo/switch_commit endpoints
13+
# Set to 1 to make read-only endpoints public.
1614
CODE_GRAPH_PUBLIC=0
15+
16+
# Limit /api/analyze_folder to this directory tree. Leave commented to use
17+
# the repository root as the default allowed directory.
18+
# ALLOWED_ANALYSIS_DIR=/absolute/path/to/projects
19+
20+
# LiteLLM model used by /api/chat
21+
MODEL_NAME=gemini/gemini-flash-lite-latest
22+
23+
# Provider credential for the default Gemini model. Change this to the
24+
# appropriate provider key if you change MODEL_NAME.
25+
GEMINI_API_KEY=<YOUR_GEMINI_API_KEY>
26+
27+
# Optional Uvicorn bind settings used by start.sh / make run-*
28+
HOST=0.0.0.0
29+
PORT=5000

‎README.md‎

Lines changed: 123 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -19,45 +19,42 @@ Connect and ask questions: [![Discord](https://img.shields.io/badge/Discord-%235
1919

2020
```
2121
code-graph/
22-
├── api/ # Python backend (Flask)
23-
│ ├── index.py # Main Flask app with API routes
24-
│ ├── graph.py # Graph operations (FalkorDB)
25-
│ ├── llm.py # LLM integration for chat
26-
│ ├── project.py # Project management
27-
│ ├── info.py # Repository info
28-
│ ├── prompts.py # LLM prompts
29-
│ ├── auto_complete.py # Auto-completion
30-
│ ├── analyzers/ # Source code analyzers (Python, Java, C, C#)
31-
│ ├── entities/ # Entity models
32-
│ ├── git_utils/ # Git operations
33-
│ └── code_coverage/ # Code coverage utilities
22+
├── api/ # Python backend (FastAPI)
23+
│ ├── index.py # FastAPI app, auth deps, API routes, SPA serving
24+
│ ├── graph.py # FalkorDB graph operations
25+
│ ├── llm.py # GraphRAG + LiteLLM chat integration
26+
│ ├── project.py # Repository cloning and analysis orchestration
27+
│ ├── info.py # Repository metadata stored in Redis/FalkorDB
28+
│ ├── prompts.py # LLM system and prompt templates
29+
│ ├── auto_complete.py # Prefix search helper
30+
│ ├── analyzers/ # Source analyzers (Python, Java, C#)
31+
│ ├── entities/ # Graph/entity models
32+
│ ├── git_utils/ # Git history graph utilities
33+
│ └── code_coverage/ # Coverage utilities
3434
├── app/ # React frontend (Vite)
3535
│ ├── src/ # Frontend source code
36-
│ │ ├── App.tsx # Main application component
37-
│ │ ├── main.tsx # Entry point
38-
│ │ ├── components/ # React components
39-
│ │ └── lib/ # Utility functions
4036
│ ├── public/ # Static assets
41-
│ ├── package.json # Frontend dependencies
42-
│ ├── vite.config.ts # Vite configuration
43-
│ └── tsconfig.json # TypeScript configuration
44-
├── tests/ # Backend tests
45-
├── e2e/ # End-to-end tests (Playwright)
46-
├── Dockerfile # Unified Docker build
47-
├── docker-compose.yml # Docker Compose setup
48-
├── Makefile # Development commands
49-
├── start.sh # Container startup script
50-
├── pyproject.toml # Python project configuration
51-
└── .env.template # Environment variables template
37+
│ ├── package.json # Frontend dependencies and scripts
38+
│ ├── vite.config.ts # Vite config and /api proxy for dev mode
39+
│ └── tsconfig*.json # TypeScript config
40+
├── tests/ # Backend/unit and endpoint tests
41+
├── e2e/ # End-to-end helpers and Playwright assets
42+
├── Dockerfile # Unified container image
43+
├── docker-compose.yml # Local FalkorDB + app stack
44+
├── Makefile # Common dev/build/test commands
45+
├── start.sh # Container entrypoint
46+
├── pyproject.toml # Python package and dependency config
47+
└── .env.template # Example environment variables
5248
```
5349

5450
## Running Locally
5551

5652
### Prerequisites
5753

58-
- Python 3.12+
54+
- Python `>=3.12,<3.14`
5955
- Node.js 20+
60-
- FalkorDB instance (local or cloud)
56+
- [`uv`](https://docs.astral.sh/uv/)
57+
- A FalkorDB instance (local or cloud)
6158

6259
### 1. Start FalkorDB
6360

@@ -69,152 +66,181 @@ code-graph/
6966
docker run -p 6379:6379 -it --rm falkordb/falkordb
7067
```
7168

72-
### 2. Set Up Environment Variables
69+
### 2. Configure environment variables
7370

74-
Copy the template and configure:
71+
Copy the template and adjust it for your setup:
7572

7673
```bash
7774
cp .env.template .env
7875
```
7976

8077
| Variable | Description | Required | Default |
8178
|----------|-------------|----------|---------|
82-
| `OPENAI_API_KEY` | Your OpenAI API key for code analysis | Yes | - |
83-
| `SECRET_TOKEN` | User-defined token for request authorization | Yes | - |
84-
| `FALKORDB_HOST` | FalkorDB server hostname | No | localhost |
85-
| `FALKORDB_PORT` | FalkorDB server port | No | 6379 |
79+
| `FALKORDB_HOST` | FalkorDB hostname | No | `localhost` |
80+
| `FALKORDB_PORT` | FalkorDB port | No | `6379` |
81+
| `FALKORDB_USERNAME` | Optional FalkorDB username | No | empty |
82+
| `FALKORDB_PASSWORD` | Optional FalkorDB password | No | empty |
83+
| `SECRET_TOKEN` | Token checked by protected endpoints | No | empty |
84+
| `CODE_GRAPH_PUBLIC` | Set `1` to skip auth on read-only endpoints | No | `0` |
85+
| `ALLOWED_ANALYSIS_DIR` | Root path allowed for `/api/analyze_folder` | No | repository root |
86+
| `MODEL_NAME` | LiteLLM model used by `/api/chat` | No | `gemini/gemini-flash-lite-latest` |
87+
| `HOST` | Optional Uvicorn bind host for `start.sh`/`make run-*` | No | `0.0.0.0` or `127.0.0.1` depending on command |
88+
| `PORT` | Optional Uvicorn bind port for `start.sh`/`make run-*` | No | `5000` |
8689

87-
Edit `.env` with your values:
90+
The chat endpoint also needs the provider credential expected by your chosen `MODEL_NAME`. The default model is Gemini, so set `GEMINI_API_KEY` unless you switch to a different LiteLLM provider/model.
8891

89-
```bash
90-
FALKORDB_HOST=localhost
91-
FALKORDB_PORT=6379
92-
OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>
93-
SECRET_TOKEN=<YOUR_SECRET_TOKEN>
94-
```
92+
### Authentication behavior
93+
94+
- Send `Authorization: Bearer <SECRET_TOKEN>` (or the raw token string) when `SECRET_TOKEN` is configured.
95+
- Read endpoints use the `public_or_auth` dependency.
96+
- Mutating endpoints (`/api/analyze_folder`, `/api/analyze_repo`, `/api/switch_commit`) use the `token_required` dependency.
97+
- If `SECRET_TOKEN` is unset, the current implementation accepts requests without an `Authorization` header.
98+
- Setting `CODE_GRAPH_PUBLIC=1` makes the read-only endpoints public even when `SECRET_TOKEN` is configured.
9599

96-
### 3. Install Dependencies
100+
### 3. Install dependencies
97101

98102
```bash
99103
# Install backend dependencies
100-
pip install -e ".[test]"
104+
uv sync --all-extras
101105

102106
# Install frontend dependencies
103107
npm install --prefix ./app
108+
109+
# Optional: install Playwright dependencies from the repo root
110+
npm install
104111
```
105112

106-
Or using Make:
113+
If you do not use `uv`, `pip install -e ".[test]"` also installs the backend package and test dependencies.
114+
115+
### 4. Run the app
116+
117+
**Backend API with auto-reload:**
107118

108119
```bash
109-
make install
120+
uv run uvicorn api.index:app --host 127.0.0.1 --port 5000 --reload
110121
```
111122

112-
### 4. Build & Start
123+
**Frontend hot-reload with Vite:**
113124

114125
```bash
115-
# Build the frontend
116-
npm --prefix ./app run build
126+
# Terminal 1: backend API
127+
uv run uvicorn api.index:app --host 127.0.0.1 --port 5000 --reload
117128

118-
# Start the backend (serves both API and frontend)
119-
flask --app api/index.py run --debug
129+
# Terminal 2: Vite dev server
130+
cd app && npm run dev
120131
```
121132

122-
The application will be available at [http://localhost:5000](http://localhost:5000).
123-
124-
### Development Mode
133+
The Vite dev server runs on `http://localhost:3000` and proxies `/api/*` requests to `http://127.0.0.1:5000`.
125134

126-
For frontend development with hot-reload:
135+
**Single-process built frontend + backend:**
127136

128137
```bash
129-
# Terminal 1: Start the Python backend
130-
flask --app api/index.py run --debug --port 5000
131-
132-
# Terminal 2: Start the Vite dev server (proxies API calls to backend)
133-
cd app && npm run dev
138+
npm --prefix ./app run build
139+
uv run uvicorn api.index:app --host 0.0.0.0 --port 5000
134140
```
135141

136-
The Vite dev server runs on `http://localhost:3000` and proxies API requests to the Flask backend on port 5000.
142+
In this mode, the FastAPI app serves the built React SPA from `app/dist` on `http://localhost:5000`.
137143

138144
### Using Make
139145

140146
```bash
141-
make install # Install all dependencies
142-
make build-dev # Build frontend (development)
143-
make build-prod # Build frontend (production)
144-
make run-dev # Build + start dev server
145-
make run-prod # Build + start production server
146-
make test # Run backend tests
147-
make lint # Run frontend linting
148-
make clean # Clean build artifacts
147+
make install # Install backend + frontend dependencies
148+
make build-dev # Build frontend in development mode
149+
make build-prod # Build frontend for production
150+
make run-dev # Build dev frontend + run Uvicorn with reload
151+
make run-prod # Build prod frontend + run Uvicorn
152+
make test # Run backend pytest suite
153+
make lint # Run Ruff + frontend type-check
154+
make e2e # Run Playwright tests from repo root
155+
make clean # Remove build/test artifacts
149156
```
150157

158+
`make test` currently points at the right backend test entrypoint, but some legacy analyzer/git-history tests still need maintenance before the suite passes on a clean checkout.
159+
151160
## Running with Docker
152161

153162
### Using Docker Compose
154163

155164
```bash
156-
docker-compose up
165+
docker compose up --build
157166
```
158167

159-
This starts both FalkorDB and the CodeGraph application.
168+
This starts FalkorDB and the CodeGraph app together. The checked-in compose file sets `CODE_GRAPH_PUBLIC=1` for the app service.
160169

161-
### Using Docker Directly
170+
### Using Docker directly
162171

163172
```bash
164173
docker build -t code-graph .
165174

166175
docker run -p 5000:5000 \
167176
-e FALKORDB_HOST=host.docker.internal \
168177
-e FALKORDB_PORT=6379 \
169-
-e OPENAI_API_KEY=<YOUR_KEY> \
170-
-e SECRET_TOKEN=<YOUR_TOKEN> \
178+
-e MODEL_NAME=gemini/gemini-flash-lite-latest \
179+
-e GEMINI_API_KEY=<YOUR_GEMINI_API_KEY> \
180+
-e SECRET_TOKEN=<YOUR_SECRET_TOKEN> \
171181
code-graph
172182
```
173183

174184
## Creating a Code Graph
175185

176-
### Analyze a Local Folder
186+
### Analyze a local folder
187+
188+
`analyze_folder` only accepts paths under `ALLOWED_ANALYSIS_DIR` (defaults to the repository root unless you override it).
177189

178190
```bash
179-
curl -X POST http://127.0.0.1:5000/analyze_folder \
191+
curl -X POST http://127.0.0.1:5000/api/analyze_folder \
180192
-H "Content-Type: application/json" \
181-
-H "Authorization: <YOUR_SECRET_TOKEN>" \
193+
-H "Authorization: Bearer <YOUR_SECRET_TOKEN>" \
182194
-d '{"path": "<FULL_PATH_TO_FOLDER>", "ignore": [".github", ".git"]}'
183195
```
184196

185-
### Analyze a GitHub Repository
197+
### Analyze a Git repository
186198

187199
```bash
188-
curl -X POST http://127.0.0.1:5000/analyze_repo \
200+
curl -X POST http://127.0.0.1:5000/api/analyze_repo \
189201
-H "Content-Type: application/json" \
190-
-H "Authorization: <YOUR_SECRET_TOKEN>" \
191-
-d '{"repo_url": "https://github.com/user/repo"}'
202+
-H "Authorization: Bearer <YOUR_SECRET_TOKEN>" \
203+
-d '{"repo_url": "https://github.com/user/repo", "ignore": [".github", ".git"]}'
204+
```
205+
206+
### List indexed repositories
207+
208+
```bash
209+
curl http://127.0.0.1:5000/api/list_repos
192210
```
193211

194212
## Supported Languages
195213

196-
- Python
197-
- Java
198-
- C
199-
- C#
214+
`api/analyzers/source_analyzer.py` currently enables these analyzers:
200215

201-
Support for additional languages is planned.
216+
- Python (`.py`)
217+
- Java (`.java`)
218+
- C# (`.cs`)
219+
220+
A C analyzer exists in the source tree, but it is commented out and is not currently registered.
202221

203222
## API Endpoints
204223

224+
### Read endpoints
225+
226+
| Method | Endpoint | Description |
227+
|--------|----------|-------------|
228+
| GET | `/api/list_repos` | List all indexed repositories |
229+
| GET | `/api/graph_entities?repo=<name>` | Fetch a subgraph for a repository |
230+
| POST | `/api/get_neighbors` | Return neighboring nodes for the provided IDs |
231+
| POST | `/api/auto_complete` | Prefix-search indexed entities |
232+
| POST | `/api/repo_info` | Return repository stats and saved metadata |
233+
| POST | `/api/find_paths` | Find paths between two graph nodes |
234+
| POST | `/api/chat` | Ask questions over the code graph via GraphRAG |
235+
| POST | `/api/list_commits` | List commits from the repository's git graph |
236+
237+
### Mutating endpoints
238+
205239
| Method | Endpoint | Description |
206240
|--------|----------|-------------|
207-
| GET | `/list_repos` | List all available repositories |
208-
| GET | `/graph_entities?repo=<name>` | Get graph entities for a repository |
209-
| POST | `/get_neighbors` | Get neighbors of specified nodes |
210-
| POST | `/auto_complete` | Auto-complete entity names |
211-
| POST | `/repo_info` | Get repository information |
212-
| POST | `/find_paths` | Find paths between two nodes |
213-
| POST | `/chat` | Chat with the code graph using natural language |
214-
| POST | `/analyze_folder` | Analyze a local source folder |
215-
| POST | `/analyze_repo` | Analyze a GitHub repository |
216-
| POST | `/list_commits` | List commits of a repository |
217-
| POST | `/switch_commit` | Switch to a specific commit |
241+
| POST | `/api/analyze_folder` | Analyze a local source folder |
242+
| POST | `/api/analyze_repo` | Clone and analyze a git repository |
243+
| POST | `/api/switch_commit` | Switch the indexed repository to a specific commit |
218244

219245
## License
220246

0 commit comments

Comments
 (0)