NarraNexus · Contributing

Development Setup

Set up the NarraNexus development environment from source — backend, frontend, and all supporting services.

Prerequisites

Python 3.11+Backend runtime

Node.js 18+Frontend build tooling

GitVersion control

MakeTask runner (see Makefile)

Clone & Install

Clone

git clone https://github.com/NetMindAI-Open/NarraNexus.git && cd NarraNexus

Backend dependencies

pip install -e ".[dev]"

Frontend dependencies

cd frontend && npm install

Environment

cp .env.example .env

Running Services

Four processes need to run in parallel, each in its own terminal:

make dev-backendFastAPI server — port 8000

make dev-mcpMCP tool servers for all modules

make dev-pollerModulePoller — instance state monitoring

make dev-frontendVite dev server

Quality Checks

make lintRuff (backend) + ESLint (frontend)

make typecheckPyright (backend) + tsc (frontend)

make testRun pytest test suite

make db-sync-dryPreview database schema changes

make db-syncApply database schema changes

Project Structure

NarraNexus/
├── backend/              # FastAPI routes
├── frontend/             # React + Vite
├── src/xyz_agent_context/
│   ├── agent_runtime/    # 7-step pipeline
│   ├── context_runtime/  # Context assembly
│   ├── narrative/        # Narrative system
│   ├── module/           # All modules
│   ├── schema/           # Pydantic models
│   ├── repository/       # Data access layer
│   ├── services/         # Background services
│   └── utils/            # Shared utilities
└── .mindflow/            # Documentation system