From White Screens to Gemini Streams: Unpacking a Productive Dev Session

Every development sprint has its moments of triumph, head-scratching challenges, and those satisfying "aha!" revelations. Our latest session, wrapping up on a crisp February morning, was no prime example. We set out with ambitious goals: squashing a critical UI bug, enhancing our AI capabilities with a new LLM provider, and smoothing out a tricky conversation flow.

Here’s a deep dive into what we accomplished, the hurdles we overcame, and the lessons we learned along the way.

Executive Summary: A Morning of Progress

Our primary mission for this session was clear:

Eliminate the dreaded persona selection white screen.
Integrate Google Gemini as a new Large Language Model (LLM) provider.
Fix the discussion retry flow to ensure seamless AI interaction.
Conduct thorough QA to confirm key functionalities.

By the end of the session, all core fixes and the Gemini integration were in place, type-checking flawlessly, and the development server humming.

Tackling the Elusive White Screen: Our Persona Selection Saga

The most critical bug on our plate was an intermittent white screen crash when selecting a persona within a workflow. These kinds of bugs are notorious – hard to reproduce, often lacking clear error messages, and generally frustrating.

The Debugging Journey

Our initial attempts at static analysis to pinpoint the exact crash site proved fruitless. No obvious null accesses or type errors jumped out from the code. This suggested a more complex interplay of factors.

Our solution involved a multi-pronged approach:

Robust Error Handling: The first line of defense was to implement a global ErrorBoundary component. Wrapping our main dashboard content in src/app/(dashboard)/layout.tsx ensures that even if an unexpected error occurs deeper in the component tree, the user sees a graceful fallback instead of a blank page, and we get a stack trace.
Eliminating Race Conditions: We discovered a duplicate refetch() call in an inline onSuccess handler for the persona selection mutation. A global onSuccess already handled this, creating a potential race condition or unnecessary re-renders. Removing the redundant call streamlined the data flow.
Defensive Coding: Added onError handlers to the persona select mutation for better error logging and state cleanup. We also introduced null guards (?? []) on step.compareProviders and step.comparePersonas to prevent crashes from unexpected null or undefined values.
Environment Hygiene: A crucial, often overlooked step: restarting the dev server with a cleared .next cache. This resolved a subtle, stale SQL ambiguous column error that had been lurking from a previous session, likely contributing to the instability.

Lesson Learned: White screens are rarely caused by a single, obvious flaw. They often stem from a combination of race conditions, unhandled errors, missing defensive checks, and even stale build caches. A systematic approach, starting with robust error boundaries, is key.

Bringing Google Gemini into the Fold: A New LLM Powerhouse

Expanding our platform's AI capabilities is a continuous effort, and this session saw the full integration of Google Gemini. This wasn't just about plugging in an API key; it involved handling the nuances of Gemini's API.

Implementation Details

Our src/server/services/llm/adapters/google.ts file went from a stub to a fully functional provider:

Completion & Streaming: We implemented both complete() for single-shot responses via the generateContent endpoint and stream() for real-time interaction using streamGenerateContent?alt=sse.
Role Mapping: Gemini uses a model role for AI responses, unlike the more common assistant. We implemented mapping to ensure consistent internal representation.
Message Merging & Ordering: Gemini has specific requirements: consecutive messages from the same role must be merged, and the conversation must always start with a user message. Our adapter now intelligently handles these formatting rules.
System Prompts: System instructions are sent separately via systemInstruction, rather than as part of the main contents array, which we accounted for.
Token Usage: We integrated usageMetadata to accurately track token consumption.
Default Model: The integration defaults to gemini-2.0-flash, offering a good balance of performance and cost.

Insight: Integrating new LLM providers goes beyond simple API calls. Each model has its own quirks regarding message formats, role names, and conversation turn requirements. A robust adapter needs to abstract these differences to provide a consistent interface.

Seamless Conversation Retries: Fixing the Discussion Flow

Another user experience blocker was an issue with retrying a discussion with a different AI provider. Users would select "retry," but the discussion service would immediately return "done" without generating a new response.

The Root Cause & Solution

The culprit was subtle: when retrying, our Server-Sent Events (SSE) connection was re-established without the crucial auto=1 flag. Our processDiscussion() function, designed to ensure the last message in a new turn is from the user, saw the previous assistant messages and prematurely concluded the discussion was "done."

The fix was straightforward but critical: we added setIsAutoRound(true) immediately before incrementing sseKey in the retry onSuccess callback. This ensures the SSE URL correctly includes ?auto=1, signaling to the backend that a new, auto-generated round of discussion should commence.

Lesson Learned: Small flags and parameters in API calls, especially in stateful or streaming contexts like SSE, can have disproportionately large impacts on application logic. Always verify that all necessary parameters are being sent when re-initializing complex flows.

Validated Progress: User-Facing Confirmations

Beyond the core fixes and features, we also confirmed the stability of several key user-facing components:

Persona portraits displaying correctly on overview and detail pages.
Full CRUD functionality for the Project Notes tab.
The animated heartbeat in the sidebar.
The Memory Intelligence panel in the analytics dashboard.
Mermaid diagrams rendering as expected in the Docs tab.
Correct project selector and compare persona labels during workflow creation.

This broad QA sweep ensures that our changes haven't introduced regressions elsewhere.

Looking Ahead: What's Next?

With these significant milestones achieved, our immediate next steps include:

Thorough end-to-end testing of the Google Gemini integration.
Verifying the discussion retry-with-another-provider flow.
Confirming the persona selection bug is definitively squashed in workflow creation.
Committing and pushing all changes from this productive session.
Moving on to our next LLM integration: Ollama.
Implementing RLS policies for our project_notes table.
General cleanup of our .gitignore and an audit of remaining SSE endpoints for safeEnqueue.

It was a demanding but highly rewarding session, solidifying our platform's stability and expanding its AI horizons. Stay tuned for more updates as we continue to build and refine!