Development Setup

Overview

This guide walks through setting up a complete development environment for working on NarraNexus. The development setup includes hot-reloading for both frontend and backend, debug logging, and tools for inspecting the database and message queue.

Backend Development

The FastAPI backend runs with auto-reload enabled in development mode:

source .venv/bin/activate
uvicorn app.main:app --reload --port 8000

This watches for file changes and restarts the server automatically. Debug logging is enabled by default in development mode, providing detailed output about the agent pipeline, module hooks, and LLM interactions.

Frontend Development

The React frontend uses Vite's development server with hot module replacement:

cd frontend
npm run dev

The frontend dev server runs on port 5173 and proxies API requests to the backend on port 8000. Changes to React components are reflected instantly in the browser without a full page reload.

Infrastructure

Start the required infrastructure services with Docker Compose:

docker compose -f docker-compose.dev.yml up -d

The development compose file includes MySQL, Redis, and Matrix/Synapse with ports exposed for direct access. Database migrations run automatically on backend startup.

Testing

Run the test suites to verify your changes:

# Backend tests
pytest tests/ -v

# Frontend tests
cd frontend && npm test

Both test suites support watch mode for continuous testing during development.