nyxCore: Git Code Review Tool

Technical Documentation — Architecture, Algorithms, and Scientific Foundations

Version: 1.0 Date: 2026-03-10 Classification: Internal Technical Reference

Table of Contents

1. Neural Constellation Board
   1. System Architecture
   2. Dimensionality Reduction: UMAP Theory
   3. Embedding Pipeline
   4. Coordinate Normalization
   5. Proximity Clustering
   6. Visual Encoding System
   7. Rendering Pipeline: React Three Fiber
   8. Interaction Model
   9. Performance Optimization
2. Git Code Review Tool
   1. System Architecture
   2. Security Model: BYOK Token Resolution
   3. GitHub REST API Layer
   4. AI-Powered Code Review
   5. Unified Diff Parsing Algorithm
   6. tRPC Procedure Architecture
   7. UI Component Hierarchy
   8. Error Handling & Resilience
3. References

2. Git Code Review Tool

The Git Code Review Tool integrates AI-powered analysis directly into the pull request workflow. It fetches PR diffs from GitHub, runs multi-provider LLM review, extracts structured findings, and presents them alongside the diff with file-level navigation and scoring.

2.1 System Architecture

2.2 Security Model: BYOK Token Resolution

All GitHub API calls use the tenant's encrypted Personal Access Token retrieved via resolveGitHubToken(). The token is stored as AES-256-GCM ciphertext in the api_keys table and decrypted per-request. No GitHub credentials are ever stored in plaintext or cached in application memory.

Required PAT scopes for code review:

• repo — read access to private repositories and pull requests
• read:org — enumerate organization repositories (optional)

2.3 GitHub REST API Layer

The review tool uses three GitHub REST API endpoints:

Pagination is handled with up to 3 pages of results (100 PRs per page). File diffs include the patch field containing the unified diff text, which is parsed by the diff parser into structured hunks.

2.4 AI-Powered Code Review

The review engine sends the PR diff to the configured LLM provider with a structured prompt requesting JSON output. The prompt instructs the model to:

1. Identify issues by category: security, performance, correctness, style, documentation
2. Assign severity: critical, high, medium, low
3. Locate findings to specific file paths and line numbers within the diff
4. Provide actionable suggestions

Each finding is persisted as a ReviewFinding record and associated with the parent PullRequestReview.

Multi-Persona Analysis: When multiple personas are configured for the review workflow, each persona runs independently against the same diff, producing persona-specific findings. The findings are then merged and de-duplicated by a consensus scoring step that weights convergent findings (flagged by multiple personas) with higher severity.

Provider Fan-Out: The review can be configured to run across multiple LLM providers simultaneously (e.g., Anthropic + OpenAI). Each provider's findings are aggregated, with cross-provider consensus elevating finding confidence.

2.5 Unified Diff Parsing Algorithm

The diff parser transforms GitHub's unified diff text into a structured representation for display and line-number mapping.

Input format (GitHub unified diff):

@@ -10,7 +10,8 @@
 context line
-removed line
+added line
+new added line
 context line

Parsing steps:

1. Split on @@ -N,M +N,M @@ hunk headers (regex: /^@@ -(\d+),(\d+) \+(\d+),(\d+) @@/)
2. For each hunk, track oldLine and newLine counters starting from the hunk's base offsets
3. Classify each line: context (space), deletion (-), addition (+)
4. Build a lineMap from new-file line numbers to diff position for finding anchoring

The resulting structure enables the DiffViewer component to render syntax-highlighted diffs with inline finding annotations at precise line positions.

2.6 tRPC Procedure Architecture

The codeReview router exposes:

The startReview mutation is rate-limited to the LLM tier (10 req/min) to prevent runaway API costs from rapid re-runs.

2.7 UI Component Hierarchy

CodeReviewView
├── PRSelector              — repository + branch picker
├── PRList                  — paginated PR cards with status badges
├── DiffViewer              — split/unified diff with syntax highlighting
│   ├── FileTree            — collapsible file navigation sidebar
│   ├── HunkRenderer        — individual diff hunk with line numbers
│   └── FindingAnnotation   — inline finding marker with tooltip
└── ReviewPanel             — findings summary, severity breakdown, actions
    ├── FindingCard         — expandable finding with suggestion
    └── ConsensusScore      — multi-provider agreement indicator

2.8 Error Handling & Resilience

References

1. McInnes, L., Healy, J., & Melville, J. (2018). UMAP: Uniform Manifold Approximation and Projection for Dimension Reduction. arXiv:1802.03426.
2. Bertin, J. (1983). Semiology of Graphics. University of Wisconsin Press.
3. Ware, C. (2012). Information Visualization: Perception for Design (3rd ed.). Morgan Kaufmann.
4. Stevens, S. S. (1957). On the psychophysical law. Psychological Review, 64(3), 153–181.
5. Drcmda. (2021). React Three Fiber: A React renderer for Three.js. GitHub: pmndrs/react-three-fiber.