← nyxcore-systems
6 min read

Unlocking Seamless PR Reviews: Designing nyxCore's GitHub Workflow (and Getting Ready for AI)

Ever wondered what goes into building a robust GitHub PR review experience from scratch? Join us as we break down the design and planning phase for nyxCore's new workflow, complete with AI-assisted development.

GitHub APIPR WorkflowSystem DesignTypeScripttRPCRadix UIAI DevelopmentSoftware ArchitectureFrontend DevelopmentBackend Development

Crafting the Perfect Review: A Deep Dive into nyxCore's GitHub PR Workflow Design

Building complex applications often means integrating with external services, and for many of us, GitHub is the beating heart of our development process. At nyxCore, we're not just building features; we're building an integrated experience. That's why, rather than simply linking out to GitHub, we've embarked on an ambitious project: designing and implementing a native GitHub Pull Request (PR) review workflow directly within our project pages.

This post is a look behind the curtain, a developer's memory dump from a recent session focused entirely on the design and planning of this critical feature. It covers the architectural decisions, the codebase exploration, and the immediate next steps, all with an eye towards leveraging AI for development.

The Mission: A Native PR Review Experience

Our primary goal for this session was clear: to lay the groundwork for a comprehensive GitHub PR review workflow for nyxCore project pages. This isn't just about showing a list of PRs; it's about providing a full-fledged experience, including:

  • A dedicated "Reviews" tab on project pages.
  • An integrated diff viewer.
  • Capabilities for AI-assisted code reviews (more on this exciting part later!).
  • Seamless merge actions directly from our UI.

By the end of the session, we had a solid design document and a detailed implementation plan, ready to kick off the actual coding.

The Blueprint: Design & Implementation Plans

Before a single line of feature code was written, we focused on meticulous planning. This phase yielded two crucial documents:

  1. docs/plans/2026-03-10-pr-review-workflow-design.md: This document details the full feature specification. It covers everything from the user experience in the "Reviews" tab to the nitty-gritty of the diff viewer and how AI will integrate into the review process.
  2. docs/plans/2026-03-10-pr-review-workflow-implementation.md: Breaking down the design into actionable steps is key. This plan outlines 8 distinct tasks, emphasizing a Test-Driven Development (TDD) approach and ensuring each step is bite-sized and manageable. This structured approach is vital for maintaining momentum and clarity, especially when tackling a feature of this scope.

Architectural Reconnaissance: Navigating the nyxCore Codebase

A significant chunk of our planning involved diving deep into the existing codebase to understand how new features would integrate. Here's what we explored and learned:

  • github-connector.ts & ghFetch<T>(): Our primary interface with the GitHub API. A key discovery was that ghFetch<T>() is a private helper, not exported. This means all new GitHub PR-related functions (like listing PRs, getting details, files, comments) must reside within github-connector.ts. This enforces a clean separation of concerns and centralizes our GitHub API interactions. No Octokit here, just raw fetch power!

    typescript
    // Inside src/server/services/github-connector.ts
async function ghFetch<T>(accessToken: string, url: string, options?: RequestInit): Promise<T> {
    // ... implementation using raw fetch ...
}

// New functions will look like this:
export async function listPullRequests(accessToken: string, owner: string, repo: string): Promise<GithubPullRequest[]> {
    return ghFetch<GithubPullRequest[]>(accessToken, `https://api.github.com/repos/${owner}/${repo}/pulls`);
}

  • projects.ts Router (src/server/trpc/routers/projects.ts): This beast of a file (currently 1831 lines!) is our main projects router. It uses a sub-router pattern, handling github:, sync:, notes:, docs:, and blogPosts: routes. Our new PR review workflow will likely introduce a reviews: sub-router, keeping the project's data well-organized.

  • Project Page UI (src/app/(dashboard)/dashboard/projects/[id]/page.tsx): The UI for our project pages leverages Radix UI vertical tabs. With 13 tabs across 6 groups already, integrating a new "Reviews" tab will be straightforward, fitting neatly into the existing structure.

  • Testing Patterns: We rely on Vitest for our unit tests, making heavy use of vi.mock() for isolating components and services. This pattern will be crucial for robustly testing our new GitHub connector functions and tRPC resolvers.

Lessons Learned (The "Pain Log" that wasn't painful!)

Often, planning sessions uncover major roadblocks. Thankfully, this one was relatively smooth, but we did make some crucial discoveries that streamlined our path forward:

  1. Icon Already Present: A small win, but every little bit helps! We discovered that the GitPullRequest icon was already imported on the project page (line 38, to be precise). No need to add a new import, saving a tiny bit of overhead.
  2. Bridging Internal Projects with GitHub Repositories: Our Repository model already contains owner and repo fields. This is a game-changer! It means we can easily resolve the specific GitHub repository (owner/repo) associated with any given nyxCore project using prisma.repository.findMany({ where: { projectId, tenantId } }). This linkage is fundamental for fetching PRs relevant to a specific project.
  3. Navigating API Gateways: The Private ghFetch: As mentioned, the private nature of ghFetch<T>() dictates that all new GitHub API interaction functions must be co-located within github-connector.ts. This isn't a "pain" but a critical architectural constraint that ensures consistency and maintainability of our GitHub integration layer.

Embracing the Future: Subagent-Driven Development

Perhaps the most exciting aspect of this project is our chosen execution mode: Subagent-Driven Development. This means we'll be leveraging AI subagents to assist in writing the code for these tasks. Our immediate next step, Task 1, is specifically targeted for this approach:

  • Task 1 Target: src/server/services/github-connector.ts
  • Goal: Implement core GitHub connector PR read operations: listPullRequests, getPullRequest, getPullRequestFiles, getPullRequestComments.
  • Test Target: tests/unit/github-pr-connector.test.ts

We'll also need to keep an eye on src/server/services/llm/provider-resolver.ts to verify its signature before we get to Task 6, which involves the AI review functionality. This ensures our AI integration is robust and well-defined.

What's Next: The Road Ahead

With the design and planning complete, our journey now shifts to execution. Here's a quick look at the immediate next steps:

  1. GitHub Connector Read Operations: First up, the AI subagent will tackle the core functions to read PR data from GitHub.
  2. GitHub Connector Write Operations: Following the reads, we'll implement functions for creating review comments, submitting reviews, and merging PRs.
  3. Reviews tRPC Sub-Router: We'll create src/server/trpc/routers/reviews.ts to expose our GitHub connector functions securely via tRPC.
  4. UI Components (Reviews Tab): Building out the dedicated "Reviews" tab on the project page.
  5. UI Components (Detail Page): Crafting the individual PR detail page.
  6. UI Components (Diff Viewer): Developing an integrated diff viewer for code changes.
  7. UI Components (AI Review): Bringing the AI review functionality to life within the UI.
  8. Final Verification: A comprehensive round of tests, type checks, linting, and smoke tests to ensure everything is rock solid.

This is an exciting venture, blending robust system design with cutting-edge AI-assisted development. We're building not just a feature, but a more integrated and intelligent way to manage code reviews within nyxCore. Stay tuned for updates as we progress through these tasks!

json
{
  "thingsDone": [
    "Wrote design document for GitHub PR Review Workflow (full feature spec)",
    "Wrote implementation plan (8 TDD tasks)",
    "Explored codebase structure related to GitHub integration, routers, UI, and testing",
    "Identified architectural constraints and opportunities within `github-connector.ts`, `projects.ts`, and `Repository` model",
    "Chose Subagent-Driven execution for initial tasks"
  ],
  "pains": [
    "No major issues encountered during the design/planning phase, indicating a well-understood problem space."
  ],
  "successes": [
    "Confirmed `GitPullRequest` icon is already available, saving a minor step.",
    "Validated `Repository` model's `owner` and `repo` fields for efficient project-to-GitHub mapping.",
    "Clarified `ghFetch<T>()`'s private scope, dictating that all new GitHub PR functions must reside in `github-connector.ts` for centralized logic.",
    "Successfully completed design and implementation planning, setting a clear roadmap for development.",
    "Established a subagent-driven development strategy for execution."
  ],
  "techStack": [
    "TypeScript",
    "GitHub API",
    "tRPC",
    "Radix UI",
    "Vitest",
    "Prisma",
    "Next.js",
    "AI/LLM (Subagent-driven development)"
  ]
}