Skip to main content
This guide walks through setting up a complete development environment for contributing to CodeGraph.

​
Prerequisites

​
Required

ToolVersionPurpose
.NET SDK8.0+Core application
Node.js18+Web frontend
pnpmLatestPackage management
Neo4j5.xGraph database
GitLatestVersion control

​
Optional (for GPU development)

ToolVersionPurpose
Rust1.70+GPU layout server
Metal SDKLatestmacOS GPU
Vulkan SDKLatestLinux/Windows GPU

​
Step 1: Clone the Repository

# Clone
git clone https://github.com/rofox/codegraph.git
cd codegraph

# Create a branch for your work
git checkout -b feature/my-feature

​
Step 2: Set Up Neo4j

​
Step 3: Configure Environment

# Copy example environment
cp .env.example .env

# Edit .env
Neo4j__Uri=bolt://localhost:7687
Neo4j__Username=neo4j
Neo4j__Password=devpassword
Neo4j__Database=neo4j

​
Step 4: Build and Test

# Restore dependencies
dotnet restore

# Build all projects
dotnet build

# Run tests
dotnet test

# Run tests with coverage
dotnet test --collect:"XPlat Code Coverage"

​
Step 5: Set Up Frontend

cd src/adapters/driving/web

# Install dependencies
pnpm install

# Run development server
pnpm dev

# Run frontend tests
pnpm test

​
Step 6: Set Up GPU Server (Optional)

cd lib/graphpu

# Build
cargo build --features server --release

# Test
cargo test

# Run
./target/release/graphpu-server

​
Running the Full Stack

​
Option A: start.sh Script

./start.sh
This starts:
  • Neo4j (if not running)
  • GraphPU server
  • API server
  • Web frontend

​
Option B: Manual Start

Terminal 1 - API: 
npx @dotenvx/dotenvx run -- dotnet run --project src/adapters/driving/api
Terminal 2 - Frontend: 
cd src/adapters/driving/web && pnpm dev
Terminal 3 - GPU (optional): 
./lib/graphpu/target/release/graphpu-server

​
Project Structure

codegraph/
├── src/
│   ├── core/                    # Domain logic (work here for core changes)
│   │   ├── Domain/              # Entities
│   │   └── Ports/               # Interfaces
│   └── adapters/
│       ├── driven/              # Outbound adapters
│       │   ├── neo4j/           # Neo4j implementation
│       │   ├── roslyn/          # C# analysis
│       │   └── rustgpu/         # GPU adapter
│       └── driving/             # Inbound adapters
│           ├── api/             # REST API
│           ├── cli/             # CLI
│           └── web/             # React frontend
├── plugins/                     # Plugin implementations
├── lib/
│   └── graphpu/                 # Rust GPU server
├── tests/                       # Test projects
└── docs/                        # Documentation source

​
IDE Setup

​
Visual Studio Code

Recommended extensions:
  • C# Dev Kit
  • ESLint
  • Prettier
  • rust-analyzer (for GPU development)
// .vscode/settings.json
{
  "editor.formatOnSave": true,
  "dotnet.defaultSolution": "CodeGraph.sln"
}

​
JetBrains Rider

  1. Open CodeGraph.sln
  2. Enable “Restore NuGet packages on build”
  3. Configure Neo4j connection in run configuration

​
Visual Studio

  1. Open CodeGraph.sln
  2. Set src/adapters/driving/api as startup project
  3. Configure environment variables in launchSettings.json

​
Debugging

​
API Server

# With debugging enabled
dotnet run --project src/adapters/driving/api --configuration Debug
Attach debugger to the running process, or use IDE debugging.

​
Frontend

cd src/adapters/driving/web
pnpm dev
Open browser DevTools for debugging.

​
Tests

# Run specific test
dotnet test --filter "FullyQualifiedName~MyTestClass.MyTestMethod"

# Run with debugger
dotnet test --no-build --logger "console;verbosity=detailed"

​
Common Tasks

​
Adding a New Overlay Plugin

  1. Create project in plugins/
  2. Implement IOverlayPlugin
  3. Register in Program.cs
  4. Add tests

​
Adding an API Endpoint

  1. Add method to appropriate controller in src/adapters/driving/api/Controllers/
  2. Add corresponding port method if needed
  3. Add tests
  4. Update API documentation

​
Modifying the Frontend

  1. Edit files in src/adapters/driving/web/src/
  2. Hot reload will update automatically
  3. Add tests in __tests__/

​
Troubleshooting

dotnet restore --force
dotnet build --no-incremental
  • Check Neo4j is running: docker ps or Neo4j Desktop
  • Verify credentials in .env
  • Check port 7687 is not blocked
cd src/adapters/driving/web
rm -rf node_modules
pnpm install
pnpm dev
  • Ensure Rust is installed: rustc --version
  • macOS: Xcode command line tools installed
  • Linux: Vulkan SDK installed

​
Getting Help

  • Check existing issues on GitHub
  • Ask in GitHub Discussions
  • Review the architecture docs
  • Read the codebase - it’s well documented!
Happy coding!