PR Review Flow

End-to-end workflow from GitHub webhook to posted review

Overview

Nectr automatically reviews every pull request using an AI-powered workflow that combines diff analysis, contextual intelligence from Neo4j and Mem0, and optional MCP integrations. When a PR is opened or updated, GitHub sends a webhook that triggers the review pipeline.

The entire review process runs asynchronously in the background, returning an HTTP 200 immediately to avoid webhook timeouts.

Architecture Diagram

  Developer opens / updates a Pull Request on GitHub
           │
           ▼
  GitHub → POST /api/v1/webhooks/github
           │
           ├─ Verify HMAC-SHA256 signature
           ├─ Deduplicate (ignore duplicate events within 1hr)
           ├─ Create Event row (status = pending)
           └─ Return HTTP 200 immediately
                    │
                    ▼
  BackgroundTask: process_pr_in_background()
           │
           ├─ 1. Fetch PR data from GitHub
           │      get_pr_diff()  get_pr_files()  get_file_content()
           │
           ├─ 2. Pull MCP context (if configured)
           │      ├─ Linear: linked issues & task descriptions
           │      ├─ Sentry: related errors for changed files
           │      └─ Slack: relevant channel messages
           │
           ├─ 3. Build ReviewContext (parallel)
           │      ├─ Mem0: project patterns, decisions, rules
           │      ├─ Mem0: developer-specific patterns & strengths
           │      ├─ Neo4j: file experts (who touched these files most)
           │      └─ Neo4j: related past PRs with file overlap
           │
           ├─ 4. AI Analysis — two modes (set PARALLEL_REVIEW_AGENTS)
           │
           │      STANDARD (default)               PARALLEL (opt-in)
           │      ──────────────────               ────────────────────
           │      Single agentic loop              asyncio.gather() runs:
           │      with 8 MCP-style tools           ├─ Security agent
           │      (search code, fetch              ├─ Performance agent
           │       issues, get errors…)            └─ Style agent
           │                                        ▼
           │                                  Synthesis agent combines
           │                                  all three into final review
           │
           ├─ 5. Post Review on GitHub PR
           │      • Posts as your GitHub account (PAT)
           │      • Inline review comments + top-level summary
           │
           ├─ 6. Index PR in Neo4j Graph
           │      Creates: PullRequest + Developer nodes
           │      Edges:   TOUCHES → Files
           │               AUTHORED_BY → Developer
           │               CLOSES → Issues
           │
           ├─ 7. Extract & Store Memories in Mem0
           │      Claude extracts: project_pattern, decision,
           │      developer_pattern, developer_strength, risk_module,
           │      contributor_profile
           │
           └─ 8. Update Event status → completed / failed

Workflow Stages

Configuration

Standard vs Parallel Mode

Set the PARALLEL_REVIEW_AGENTS environment variable to enable parallel specialized agents:

# Standard mode (default) — single agentic loop
PARALLEL_REVIEW_AGENTS=false

# Parallel mode — 3 specialized agents + synthesis
PARALLEL_REVIEW_AGENTS=true

When to use parallel mode:

• Larger PRs (>500 lines) where specialized analysis helps
• Security-critical repos that need thorough security review
• High-traffic repos where you want faster turnaround (parallel = faster)

When to use standard mode:

• Small to medium PRs (<500 lines)
• Repos where context depth matters more than speed
• When you want Claude to follow its own reasoning thread

MCP Integration (Optional)

Set these environment variables to enable MCP context sources:

# Linear integration
LINEAR_MCP_URL=https://linear-mcp.example.com
LINEAR_API_KEY=lin_api_...

# Sentry integration
SENTRY_MCP_URL=https://sentry-mcp.example.com
SENTRY_AUTH_TOKEN=...

# Slack integration
SLACK_MCP_URL=https://slack-mcp.example.com

If not set, Nectr silently skips that integration — reviews still work without them.

Performance

Average Review Time

Standard mode: 15-30 seconds

Parallel mode: 10-20 seconds

Context Sources

GitHub: PR diff, files, issues

Neo4j: File experts, related PRs

Mem0: Project patterns, developer habits

MCP: Linear, Sentry, Slack (optional)

Error Handling

Nectr handles failures gracefully at every stage:

• GitHub API errors: Logged, workflow marked as failed, no review posted
• Neo4j unavailable: Silently skips graph queries, continues with Mem0 context
• Mem0 unavailable: Silently skips memory queries, continues with Neo4j context
• MCP integration errors: Logged, continues without that integration’s data
• Review posting failure: Attempts GitHub review first, falls back to flat comment

If the PR review fails completely, check the /api/v1/events endpoint to see the error details stored in the Event record.

Related Files

• app/services/pr_review_service.py — Main orchestrator (view source)
• app/services/ai_service.py — Claude integration + parallel agents (view source)
• app/integrations/github/client.py — GitHub REST API client (view source)
• app/api/v1/webhooks.py — Webhook receiver (view source)