← nyxcore-systems
5 min read

From White Screens to Gemini Streams: A Deep Dive into Our Latest Dev Sprint

Join us as we recount a recent development session, tackling elusive bugs like the infamous 'white screen of death,' integrating Google Gemini, and refining our real-time discussion flows.

Next.jsLLMGeminiDebuggingFrontendBackendSSETypeScriptErrorHandling

Every development journey has its share of triumphs and tribulations. This past session was no different, a whirlwind of debugging, feature implementation, and rigorous QA. We set out with a clear mission: stamp out a particularly nasty frontend bug, integrate a powerful new LLM provider, and refine a critical user interaction. By the time the dev server hummed quietly on port 3000, we had a clean slate and some valuable lessons learned.

Let's unpack the journey.

Tackling the Elusive Bugs

Bugs are an inevitable part of software development, but some are more elusive than others. This session saw us wrestle with two particularly stubborn issues.

The Persona Selection White Screen: A Multi-Factor Mystery

The Problem: Users were occasionally hitting a blank white screen when selecting personas within our workflow module. The classic "white screen of death" is frustrating because it often provides no immediate clues. Static analysis offered no smoking gun, no obvious null pointer, no clear type error.

Our Debugging Odyssey & Solutions: This wasn't a single bug; it was a perfect storm of interacting factors. Our approach involved:

  1. Robust Error Handling: The first line of defense against a blank screen is a good ErrorBoundary. We wrapped our main dashboard content in a new src/components/error-boundary.tsx component, catching errors gracefully and providing feedback instead of a blank page. This immediately helped us get visibility into the underlying issues.
  2. Eliminating Race Conditions: We discovered a duplicate refetch() call in the persona select's inline onSuccess handler. While seemingly benign, this could lead to race conditions, especially when a global onSuccess (which already handled the refetch) was also present. Removing the redundant call smoothed out the data flow.
  3. Defensive Programming: We added onError handlers to our persona selection mutation. This not only provided crucial error logging but also allowed us to perform state cleanup in case of a failed selection.
  4. Null Guards: We implemented null guards (?? []) on step.compareProviders and step.comparePersonas to prevent potential crashes if these properties were unexpectedly undefined during rendering.
  5. Cache Invalidation: A subtle but critical step was restarting the dev server with a cleared .next cache. This resolved an ambiguous SQL column error that had been lingering from a previous session, possibly contributing to the instability.

Lesson Learned: The "white screen" often hides multiple, interacting issues. A layered approach to debugging—starting with robust error boundaries, meticulously checking for race conditions, adding defensive null checks, and ensuring a clean build environment—is crucial for resolving such complex problems.

The "Retry with Another Provider" Riddle

The Problem: Our discussion retry feature, designed to let users switch LLM providers mid-conversation, wasn't working as expected. When a user clicked "retry with another provider," the conversation would immediately mark itself as "done" without generating a new response.

The Root Cause & Solution: The culprit was a missing flag. When the retry mechanism reconnected our Server-Sent Events (SSE) stream, it failed to include the auto=1 flag in the URL. Our discussion processing service, expecting the auto flag for retries, checked if the "last message must be from the user" to initiate a new round. Without auto=1, it found the last message was from the assistant (from the previous failed attempt) and incorrectly concluded the discussion was complete.

The Fix: We simply added setIsAutoRound(true) before incrementing our sseKey in the retry onSuccess callback. This ensured the auto=1 flag was correctly appended to the SSE connection URL, allowing the service to properly process the retry as a new, user-initiated round.

Lesson Learned: Details matter, especially when interacting with APIs or real-time protocols like SSE. A single missing flag can completely alter the expected behavior, highlighting the importance of understanding API contracts and state transitions.

Integrating the Future: Google Gemini

Beyond bug fixes, a major highlight of the session was the full implementation of our Google Gemini LLM provider. This brings a powerful new option for our users, replacing a previous stub with a robust, production-ready integration.

Key Technical Details:

  • Completion & Streaming: We implemented both single-turn complete() calls using Gemini's generateContent endpoint and real-time stream() functionality via the streamGenerateContent?alt=sse endpoint, ensuring a responsive user experience.
  • Role Mapping: Gemini uses a model role for its responses, which we seamlessly mapped from our internal assistant role.
  • Merging Turns: A specific Gemini requirement is that consecutive messages from the same role must be merged. Our adapter now intelligently handles this, ensuring message payloads are correctly structured.
  • System Prompts: We leveraged Gemini's systemInstruction feature, allowing us to pass system-level guidance separately from the main contents array for cleaner prompt engineering.
  • Token Usage: We integrated usageMetadata to accurately track token consumption, which is vital for cost management and understanding model performance.
  • Default Model: The integration defaults to gemini-2.0-flash, offering a balance of speed and capability.

This integration means users with a Google API key can now seamlessly harness the power of Gemini within our platform, a significant step forward in offering diverse LLM options.

Validating Our Progress: QA Confirmed

Before wrapping up, we ran through a series of critical features, confirming their stability and functionality. It's always satisfying to see green checks across the board:

  • Persona portraits now display correctly on both overview and detail pages.
  • Project Notes tab CRUD operations are smooth.
  • The sidebar heartbeat animation pulses reliably.
  • The Analytics dashboard's Memory Intelligence panel is functional.
  • Mermaid diagrams render perfectly in the Docs tab.
  • Workflow creation, including the project selector and compare persona labels, works as expected.

What's Next?

With a clean dev environment and these significant milestones achieved, our immediate next steps involve thorough testing of the new Gemini integration and the fixed discussion retry flow. We'll then commit these changes and look ahead to implementing the Ollama provider, refining RLS policies for project_notes, and general code cleanup.

This session was a testament to the iterative nature of development – fixing, building, learning, and refining. We're excited about the stability and new capabilities these changes bring to our platform!