Getting started

This guide starts the application from the repository root. The FastAPI backend listens on port 8000; the Next.js web app listens on port 3000. Local PostgreSQL is exposed from Docker on port 5433.

PrerequisitesCopy Anchor Link

• Node.js and npm for the web app.
• Python 3.9 and the virtual environment at src/backend/.venv.
• Docker with the bash-a-postgres container.
• LM Studio when using local chat, embeddings, or graph extraction.
• A reachable Neo4j instance for graph-backed features.

Configure environment variablesCopy Anchor Link

Copy .env.example to .env in the repository root. Fill in values for services you use and keep .env out of version control.

Point DATABASE_URL at local PostgreSQL on port 5433. For local inference, set LLM_PROVIDER, LLM_MODEL, EMBEDDING_PROVIDER, and the LM Studio URLs. See Configuration for the full reference.

When possible, use separate LMSTUDIO_CHAT_URL and LMSTUDIO_EMBEDDING_URL endpoints. Sharing one model server can force it to reload a different model between retrieval and generation.

Start the databaseCopy Anchor Link

From the repository root:

docker start bash-a-postgres
docker ps --filter name=bash-a-postgres

The container may be stopped after a Docker or machine restart. Start it before making database-backed requests.

Start the APICopy Anchor Link

In one terminal:

cd src/backend
.venv/bin/uvicorn main:app --reload

The API is available at http://localhost:8000. Open http://localhost:8000/docs for FastAPI's generated OpenAPI reference.

Start the web appCopy Anchor Link

In another terminal, from the repository root:

npm install
npm run dev

Open http://localhost:3000. The browser client reads its API origin from NEXT_PUBLIC_API_URL. That value is embedded at build time, so changing it requires a rebuild.

Check service connectivityCopy Anchor Link

curl -sS http://localhost:8000/api/documents
curl -sS http://localhost:8000/api/graph/stats

The documents endpoint needs PostgreSQL. Graph statistics need Neo4j. Failure in one datastore does not by itself show that the other service is unavailable.

Run the testsCopy Anchor Link

From the repository root:

src/backend/.venv/bin/python -m pytest tests/ -q
npm test
npm run typecheck
npm run lint

Some dense-retrieval tests call the configured embedding service. Start LM Studio and load the configured embedding model if those tests fail with a connection error. See Development and testing for more checks.