Building a Better Review Workflow: Kicking Off nyxCore's GitHub PR Integration

Every developer knows the drill: context-switching between your project management tool, your IDE, and GitHub for code reviews. It's a friction point that adds up. At nyxCore, our goal is to streamline the development experience, and that means bringing critical workflows closer to where you work. Our latest initiative? Integrating a robust GitHub Pull Request review system directly into nyxCore project pages.

This post chronicles the initial design and planning session for this ambitious feature. We're not just building another GitHub integration; we're crafting a truly embedded, intelligent review experience.

The Blueprint: From Vision to Actionable Plan

Before diving into a single line of code, we laid a solid foundation. This phase was all about meticulous design and strategic planning to ensure a smooth, efficient build.

1. Comprehensive Design Document: We drafted a detailed design document (docs/plans/2026-03-10-pr-review-workflow-design.md). This isn't just a high-level overview; it's a full feature specification, covering every aspect from a dedicated "Reviews" tab, an integrated diff viewer, AI-powered review suggestions, all the way to merge actions.
2. Granular Implementation Plan: Following the design, we broke down the entire project into an eight-task implementation plan (docs/plans/2026-03-10-pr-review-workflow-implementation.md). Each task is bite-sized, adhering to Test-Driven Development (TDD) principles to ensure robustness from the start.

This structured approach is crucial for a feature of this complexity, ensuring we tackle dependencies logically and maintain code quality.

Navigating the nyxCore Labyrinth: A Codebase Reconnaissance

To build effectively, you first need to understand the terrain. We spent significant time exploring the existing nyxCore codebase, identifying key architectural patterns and potential integration points.

• GitHub Connector (github-connector.ts): This is our primary interface with the GitHub API. Interestingly, it uses a raw ghFetch<T>() helper rather than a full Octokit client. This has implications for how we'll build new API functions.
• Projects Router (projects.ts): Our src/server/trpc/routers/projects.ts file, a substantial 1800+ line behemoth, uses a sub-router pattern (github:, sync:, notes:, docs:, blogPosts:). This confirms the pattern for our new reviews: sub-router.
• Project Page UI (page.tsx): The project pages utilize Radix UI vertical tabs, currently organized into 13 tabs across 6 groups. This provides a clear path for integrating our new "Reviews" tab seamlessly.
• Testing Patterns: We're leveraging Vitest for unit testing, with vi.mock() being a critical tool for isolating components and services during testing.

Unearthing Gems: Lessons Learned from the Trenches

No design session is without its insights. We uncovered several key pieces of information that will directly influence our development path, saving us time and preventing potential roadblocks.

• The GitPullRequest Icon is Already There! A small win, but a win nonetheless. We discovered that the GitPullRequest icon is already imported and available on the project page (line 38, for the curious!). One less icon to find and import.
• Repository Resolution Made Easy: The Repository model in our Prisma schema already contains owner and repo fields. This means we can easily resolve the specific GitHub repository associated with a nyxCore project using prisma.repository.findMany({ where: { projectId, tenantId } }). This is fundamental for fetching PRs for the correct repository.
• The Private ghFetch<T>() Helper: A crucial discovery was that ghFetch<T>() is a private helper, not exported from github-connector.ts. This means all new GitHub API interaction functions (like listing PRs or fetching diffs) must reside within github-connector.ts to access this underlying fetch mechanism. This dictates our initial code structure for GitHub API integration.

Our Path Forward: Subagent-Driven Development

For the execution phase, we've opted for a Subagent-Driven execution model. This approach delegates specific, well-defined tasks to specialized subagents, allowing for parallel progress and focused development. It's like having a highly efficient, distributed team tackling the project.

Our immediate focus is on Task 1, targeting src/server/services/github-connector.ts to add core PR read operations.

What's Next on the Horizon

With the design finalized and the implementation plan in hand, our immediate next steps are clearly defined:

1. GitHub Connector Read Operations: First up is building out the core read functionality within src/server/services/github-connector.ts. This includes functions to listPullRequests, getPullRequest, getPullRequestFiles, and getPullRequestComments. We'll be writing comprehensive unit tests in tests/unit/github-pr-connector.test.ts as we go.
2. GitHub Connector Write Operations: Following the reads, we'll implement the write operations: createReviewComment, submitReview, and mergePullRequest. This completes our API layer for GitHub PRs.
3. Reviews tRPC Sub-router: We'll then create a new tRPC sub-router (src/server/trpc/routers/reviews.ts) to expose these GitHub connector functions securely to our frontend.
4. UI Components: The bulk of the user experience will come next, building the new "Reviews" tab, the detailed PR view, the interactive diff viewer, and the integrated AI review functionality.
5. AI Integration Verification: Before fully integrating the AI review, we'll verify the resolveProvider signature in src/server/services/llm/provider-resolver.ts to ensure our LLM integrations are ready.
6. Final Verification: The last step involves thorough end-to-end testing, type checking, linting, and a final smoke test to ensure everything works as expected.

We're incredibly excited about this feature. By bringing GitHub PR reviews directly into nyxCore, we're not just adding a tab; we're eliminating friction, enhancing collaboration, and ultimately making the development process more enjoyable and efficient.

Stay tuned for updates as we dive into implementation!