Visual Knowledge Explorer

Visual Knowledge Explorer is a full-stack app for uploading documents, extracting entities and relationships, building a knowledge graph, and asking graph-aware questions over your content.

The backend is a FastAPI service with Neo4j, ChromaDB, and Gemini-powered processing. The frontend is a Vite + React app that provides authentication, document upload, graph visualization, and chat-based querying.

Features

• User registration and login with JWT authentication.
• Upload and process documents such as PDF, DOCX, TXT, MD, PPTX, PNG, JPG, and JPEG.
• Automatic text parsing, chunking, embedding storage, and entity/relation extraction.
• Interactive graph visualization with node detail panels and search.
• Graph-aware question answering that combines vector retrieval with graph traversal.
• Per-user document scoping so users only see their own uploads and graphs.

Project Structure

• app/ - FastAPI backend.
• frontend/ - React + Vite frontend.
• uploads/ - Runtime file storage for uploaded documents. Not meant to be committed.
• chroma_db/ - Local ChromaDB persistence. Not meant to be committed.

Prerequisites

• Python 3.10 or newer.
• Node.js 18 or newer.
• Neo4j running locally or in the cloud.
• A Gemini API key.

Setup

1. Configure the backend environment

The backend reads configuration from a root .env file.

Use app/.env.example as the template and create a root .env with values like these:

GEMINI_API_KEY=your_gemini_api_key
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_neo4j_password_here
CHROMA_PERSIST_DIR=./chroma_db

Optional settings supported by the backend:

• GEMINI_MODEL_NAME - default: gemini-2.5-flash
• UPLOAD_DIR - default: ./uploads
• CHUNK_SIZE - default: 800
• CHUNK_OVERLAP - default: 100
• SIMILARITY_THRESHOLD - default: 0.85
• JWT_SECRET_KEY - default: development placeholder, change this for production
• JWT_ALGORITHM - default: HS256
• JWT_EXPIRE_HOURS - default: 24

2. Install backend dependencies

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

3. Install frontend dependencies

cd frontend
npm install

Run the Application

Start the backend

From the project root:

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

The backend serves the API at http://localhost:8000/api/v1 and exposes a health check at http://localhost:8000/health.

Start the frontend

In a separate terminal:

cd frontend
npm run dev

The frontend expects the API at http://localhost:8000/api/v1.

If you change the backend port or host, update frontend/src/utils/constants.js.

How to Use

1. Open the frontend in your browser after starting both services.
2. Register a new account or sign in.
3. Upload a supported document from the dashboard.
4. Wait for processing to complete. The app parses the file, extracts entities and relations, stores chunks in ChromaDB, and writes graph data to Neo4j.
5. Explore the graph visually, click nodes for details, and review source chunks.
6. Ask questions in the chat panel. The app combines semantic retrieval with graph traversal to generate answers.

API Overview

Backend routes are grouped under /api/v1.

• POST /auth/register - create a new user and receive a JWT.
• POST /auth/login - log in and receive a JWT.
• GET /auth/me - fetch the current user profile.
• POST /documents/upload - upload and process a document.
• GET /documents/ - list uploaded documents.
• GET /documents/{id}/status - check processing status.
• DELETE /documents/{id} - remove a document and its graph data.
• GET /graph - fetch the current graph.
• GET /graph/node/{node_id} - fetch node detail and neighbors.
• GET /graph/search?q=... - search graph nodes.
• POST /query - ask a graph-aware question.

Storage Notes

• Uploaded files are written to uploads/.
• ChromaDB persists locally in chroma_db/.
• Both directories are runtime data and are ignored by git.
• Do not commit your real .env file or any uploaded documents.

Development Notes

• The backend uses CORS for localhost development.
• JWT tokens are stored in browser localStorage by the frontend.
• The app scopes graph and document access to the logged-in user.
• On backend startup, the app verifies the Neo4j connection and creates constraints.

Production Checklist

• Replace the development JWT secret with a strong secret.
• Use a real Neo4j deployment and secure credentials.
• Restrict CORS origins to your production frontend domain.
• Keep .env, uploads/, chroma_db/, and virtual environment folders out of git.
• Review API keys and cloud credentials before publishing the repository.

Troubleshooting

• If the backend cannot connect to Neo4j, verify the database is running and the .env values are correct.
• If uploads fail, check that UPLOAD_DIR is writable and the file type is supported.
• If the frontend cannot reach the API, confirm the backend is running on port 8000 or update the API base URL.