Clone & Setup

Get HerConnect running locally in 8 steps — clone the repo, configure databases, start both servers, and log in.

Prerequisites

Required tools and versions before you begin.

Node.js20+(LTS recommended)

Python3.11+(with pip / venv)

Docker24+(Docker Desktop or Engine)

Git2.40+

Clone Repository

Get the HerConnect source code.

bash

git clone https://github.com/amdocs/herconnect.git
cd herconnect

The repository contains both the Next.js frontend (root) and the Python FastAPI backend (backend/).

Environment Configuration

Set up environment variables for frontend and backend.

Frontend — .env.local (project root)

env

NEXT_PUBLIC_API_URL=http://localhost:8000

Backend — backend/.env

env

# PostgreSQL
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=herconnect
POSTGRES_PASSWORD=herconnect-dev
POSTGRES_DB=herconnect

# Neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=herconnect-dev

# Milvus
MILVUS_URI=http://localhost:19530
MILVUS_TOKEN=
MILVUS_DB=default

# Azure OpenAI
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-key-here
AZURE_OPENAI_CHAT_DEPLOYMENT=gpt-4o
AZURE_OPENAI_API_VERSION=2024-12-01-preview

# Nomic Embeddings (local)
NOMIC_MODEL_NAME=nomic-ai/nomic-embed-text-v1.5
EMBEDDING_DIMENSIONS=768

# JWT Auth
JWT_SECRET=herconnect-dev-secret-change-in-production
JWT_ALGORITHM=HS256
JWT_EXPIRY_HOURS=24

# App
APP_ENV=development
CORS_ORIGINS=http://localhost:3000,http://localhost:3001
LOG_LEVEL=debug

Database Setup (Docker Compose)

Start Neo4j, PostgreSQL, Milvus, and Redis via Docker.

Create or use the provided docker-compose.yml in the project root:

yaml

version: "3.9"
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: herconnect
      POSTGRES_PASSWORD: herconnect-dev
      POSTGRES_DB: herconnect
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  neo4j:
    image: neo4j:5-community
    environment:
      NEO4J_AUTH: neo4j/herconnect-dev
    ports:
      - "7474:7474"
      - "7687:7687"
    volumes:
      - neo4jdata:/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  milvus:
    image: milvusdb/milvus:v2.4-latest
    command: milvus run standalone
    environment:
      ETCD_USE_EMBED: "true"
      COMMON_STORAGETYPE: local
    ports:
      - "19530:19530"
      - "9091:9091"
    volumes:
      - milvusdata:/var/lib/milvus

volumes:
  pgdata:
  neo4jdata:
  milvusdata:

bash

docker compose up -d

Verify all containers are running: docker compose ps

Backend Setup

Install Python dependencies and start the FastAPI server.

bash

cd backend

# Create virtual environment
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start the server
uvicorn app.main:app --reload --port 8000

The FastAPI server starts at http://localhost:8000. OpenAPI docs at http://localhost:8000/docs.

Key dependencies: FastAPI, Neo4j driver, PyMilvus, LangChain + LangGraph, Azure OpenAI, scikit-learn, sentence-transformers

Frontend Setup

Install Node dependencies and start the Next.js dev server.

bash

# From the project root
npm install

# Start the dev server
npm run dev

The Next.js 16 frontend starts at http://localhost:3000.

Key dependencies: Next.js 16, React 19, shadcn/ui, Tailwind CSS v4, Framer Motion, Recharts, Zustand, Lucide

Seed Data

Populate the Work Graph and PostgreSQL with demo data.

bash

cd backend

# Seed Neo4j Work Graph + PostgreSQL tables
python seed.py

This creates 50 employees with skills, roles, projects, teams, and relationship edges in Neo4j, plus user accounts and sample data in PostgreSQL.

Neo4j Browser

http://localhost:7474

API Health

http://localhost:8000/health

Verify & Launch

Confirm everything works and log in with demo credentials.

Health Checks

bash

# Backend health
curl http://localhost:8000/health
# Expected: {"status": "ok"}

# Frontend
open http://localhost:3000

Demo Credentials

priya.sharma@amdocs.com

Password

demo123

Available Pages

/dashboard— Dashboard

/mentorship— Mentorship & Sponsors

/leave— Leave Transition Manager

/safety— Safety Buddy

/pods— Peer Support Pods

/resources— Resources

/insights— Career Insights

/admin— Admin Dashboard

/profile— Profile

/guide— This Build Guide

You're all set!

The full HerConnect platform is running locally. Explore the build guide at /guide/build to understand how each capability was built with AI prompts.

Project Architecture

Frontend

Next.js 16 · React 19 · Tailwind v4 · shadcn/ui

localhost:3000

Backend

FastAPI · LangChain · LangGraph · scikit-learn

localhost:8000

Data Layer

Neo4j · PostgreSQL · Milvus · Redis

Docker Compose