Skip to main content

​
System Overview

Nectr is a full-stack AI code review agent built with a modern, event-driven architecture. The system consists of three main layers:
  1. Frontend - Next.js 15 + React 19 web application (Vercel)
  2. Backend - FastAPI + Uvicorn Python application (Railway)
  3. Data Layer - PostgreSQL, Neo4j knowledge graph, and Mem0 semantic memory
Nectr uses an agentic review approach where Claude fetches only the context it needs via tools, rather than receiving all context upfront. This keeps reviews focused and reduces noise.

​
Architecture Diagram

┌─────────────────────────────────────────────────────────────────────────────────┐
│                             NECTR ARCHITECTURE                                  │
└─────────────────────────────────────────────────────────────────────────────────┘

  ┌──────────┐     OAuth      ┌───────────────────────────────────────────────────┐
  │Developer │ ─────────────► │             FRONTEND (Vercel)                     │
  │  Browser │ ◄───────────── │          Next.js 15 + React 19                    │
  └──────────┘   JWT Cookie   │  /dashboard  /repos  /reviews  /analytics  /team  │
                              └──────────────────────┬────────────────────────────┘
                                                     │ REST API (axios, withCredentials)
                                                     ▼
┌────────────────────────────────────────────────────────────────────────────────────┐
│                             BACKEND (Railway)                                      │
│                           FastAPI + Uvicorn                                        │
│                                                                                    │
│  ┌──────────────────────────────────────────────────────────────────────────────┐  │
│  │                             API ROUTES                                       │  │
│  │  /auth/github            GitHub OAuth flow                                   │  │
│  │  /api/v1/webhooks        GitHub webhook receiver (per-repo)                  │  │
│  │  /api/v1/repos           Connect / disconnect / rescan repos (no redirect)   │  │
│  │  /api/v1/reviews         PR review history                                   │  │
│  │  /api/v1/analytics       Team metrics & dashboards                           │  │
│  │  /api/v1/memory          Mem0 CRUD + project map                             │  │
│  │  /health                 Status check (DB + Neo4j)                           │  │
│  │  /mcp/sse                MCP SSE stream  (GET — server → client events)      │  │
│  │  /mcp/messages           MCP JSON-RPC    (POST — client → server)            │  │
│  └──────────────────────────────────────────────────────────────────────────────┘  │
│                                                                                    │
│  ┌─────────────────────┐  ┌──────────────────────┐  ┌──────────────────────────┐  │
│  │  pr_review_         │  │  context_service     │  │      ai_service          │  │
│  │  service.py         │  │  (builds context     │  │  (Claude Sonnet 4.6)     │  │
│  │  (orchestrator)     │  │  from Neo4j + Mem0   │  │  agentic loop OR         │  │
│  │                     │  │  + MCP integrations) │  │  3 parallel agents)      │  │
│  └──────────┬──────────┘  └──────────────────────┘  └──────────────────────────┘  │
└────────────────────────────────────────────────────────────────────────────────────┘
         │           │             │              │               │
         ▼           ▼             ▼              ▼               ▼
   ┌──────────┐ ┌─────────┐ ┌──────────┐  ┌──────────┐   ┌────────────┐
   │PostgreSQL│ │  Neo4j  │ │  Mem0    │  │Anthropic │   │  GitHub    │
   │(Railway) │ │  Graph  │ │ Memory   │  │  Claude  │   │  REST API  │
   └──────────┘ └─────────┘ └──────────┘  └──────────┘   └────────────┘

​
Core Components

PR Review Service

Orchestrates the full PR review workflow from webhook to GitHub comment

AI Service

Manages Claude AI interactions with agentic tool execution

Context Service

Builds review context from Neo4j graph and Mem0 memories

Graph Builder

Builds and queries the Neo4j knowledge graph

​
Key Design Principles

​
1. Agentic Architecture

Rather than overwhelming Claude with all available context upfront, Nectr uses tool-based agentic execution. Claude decides what context it needs and fetches it on-demand:
  • read_file - Fetch full source code when diff isn’t enough
  • search_project_memory - Query project patterns and decisions
  • search_developer_memory - Look up developer-specific patterns
  • get_file_history - Find file experts and related PRs
  • get_linked_issues - Pull Linear/GitHub issues
  • get_related_errors - Fetch Sentry production errors

​
2. Event-Driven Processing

GitHub webhook events trigger background tasks that:
  1. Return HTTP 200 immediately (< 10s timeout)
  2. Process PR review asynchronously in background
  3. Update database with status and results
  4. Post review back to GitHub via REST API

​
3. Multi-Modal Memory

Structural Memory (Neo4j)
  • File → Developer relationships
  • PR → File touch patterns
  • Issue → PR closure links
Semantic Memory (Mem0)
  • Project patterns and decisions
  • Developer habits and strengths
  • Risk modules and recurring issues

​
4. Bidirectional MCP Integration

Outbound (Nectr as MCP Server)
  • Exposes PR reviews, verdicts, contributor stats via MCP
  • Claude Desktop and other agents can query Nectr’s data
Inbound (Nectr as MCP Client)
  • Pulls Linear issues, Sentry errors, Slack messages
  • Enriches PR reviews with live production context

​
Technology Stack

LayerTechnology
FrontendNext.js 15, React 19, TypeScript, TailwindCSS 4
BackendFastAPI, Uvicorn, Python 3.14
DatabasePostgreSQL (asyncpg + SQLAlchemy async)
Knowledge GraphNeo4j (async driver)
Semantic MemoryMem0
AI ModelAnthropic Claude Sonnet 4.6
GitHub IntegrationGitHub OAuth + REST API + Webhooks
MCPFastMCP (server) + httpx MCP client
Frontend HostingVercel
Backend HostingRailway
AuthGitHub OAuth → JWT (httpOnly, SameSite=None, Secure)
Token EncryptionFernet (AES-128-CBC)

​
Performance Characteristics

  • Webhook response: < 1 second (returns 200 immediately)
  • Background processing: 10-30 seconds (depends on PR size)
  • Agentic tool calls: 3-5 rounds average, ~2s per round
  • Parallel agent mode: 15-20 seconds (3 agents + synthesis)
  • Concurrent reviews: Handled by FastAPI async workers
  • Database: Connection pooling via SQLAlchemy
  • Neo4j: Indexed queries, <100ms for file experts
  • Rate limits: GitHub API (5000/hour), Anthropic (tier-based)
  • PostgreSQL: ~1 KB per event, ~5 KB per workflow run
  • Neo4j: ~100-500 nodes per repo, ~1000-5000 edges
  • Mem0: ~10-20 memories per PR review

​
Security & Privacy

  • Token Encryption: GitHub access tokens encrypted with Fernet (AES-128-CBC)
  • Webhook Verification: HMAC-SHA256 signature validation per-repo
  • JWT Auth: httpOnly cookies, SameSite=None, Secure flag
  • CORS: Strict origin allowlist for production
  • No Data Sharing: All data stays in your infrastructure

​
Next Steps

Backend Architecture

Dive into FastAPI service layer and API routes

Frontend Architecture

Explore Next.js structure and React components

Data Flow

Follow a PR review from webhook to comment

Neo4j Graph

Learn about the knowledge graph schema

Build docs developers (and LLMs) love

Get started for freeTalk to us