← nyxcore-systems
7 min read

Beyond the Bug: A Multi-Feature Dev Session and the Lessons Learned

Join me as I recount a marathon dev session, tackling everything from Next.js middleware woes and SQL ambiguities to shipping major new features like a todo importer and project reports.

Next.jsReactPostgreSQLMiddlewareFrontendBackendUXDeveloper WorkflowPWA

Every now and then, you have one of those dev sessions. The kind where you start with a sprawling mental map of tasks – bugfixes, UI tweaks, and a couple of chunky new features – and emerge hours later, blinking at the monitor, having somehow knitted it all together. This past session was precisely that: a multi-course meal of development, culminating in a clean slate and a hefty commit.

Let's dive into the journey, the triumphs, and perhaps most importantly, the hard-won lessons.

The Feature Blitz: Building New Capabilities

The primary goal was to push forward on several fronts, enhancing both user experience and core functionality.

Streamlining Workflow: Project Management & Action Points

A significant chunk of the session was dedicated to making our project and workflow management more robust.

  1. Project Selector for New Workflows: Creating a new workflow now feels much more integrated. I added a projectId state and a <select> dropdown to the workflows/new page, allowing users to associate a workflow with an existing project right from the start. Small detail, big UX win.

  2. Introducing Project Reports: This was a bigger lift. A new "Reports" tab, complete with a BarChart2 icon, now lives on the projects/[id]/page.tsx. It lists completed project workflows and, crucially, features a "Generate Report" button that fires up a ReportGeneratorModal. This lays the groundwork for powerful project analytics.

  3. The Todo Importer: From Markdown to Action Points: This was perhaps the most satisfying feature to ship. I built a new todo-importer.ts service on the backend. Its job? To parse structured markdown files from a todo/ directory (e.g., todo/backlog-2026-02-26.md). It extracts ### N. Title headings, deduces Type, Priority (P0/P1/P2), Prompt Essence, and description.

    On the frontend, an "Import todo/" button was added to the Project's Action Points tab. This triggers an importFromTodo mutation, automatically creating new action points, deduplicating by title, marking them as isAutoDetected: true, and appending their 'Prompt Essence'. This feature dramatically reduces the friction of turning raw ideas and backlogs into actionable tasks within the system.

Enhancing AI Personas & UI Polish

Our AI personas got some much-needed love, both visually and functionally.

  1. NyxCore's Custom Portrait: NyxCore, our primary AI assistant, now sports a distinct profile picture (nyx-persona-profile-pic.png). It's a small change that adds a lot to the brand and personality.

  2. Persona Specializations: All nine personas received a backfill of 1-3 specializations, a category, and traits in the database. Think "System Design/Scalability/Clean Architecture" for Sasha or "Vulnerability Analysis/OWASP/Threat Modeling" for Noor. This data is critical for future intelligent routing and persona selection.

  3. Smarter Persona Labels: On the workflow comparison view, persona buttons now show their name and their top two specializations in a dimmed, smaller text. This flex-col layout helps users quickly grasp a persona's expertise at a glance.

  4. Sidebar Heartbeat Relayout: The system heartbeat, indicating active processes, was moved inline with the NYX CORE logo in the sidebar. It's now right-aligned (justify-between), and I added subtle token flow direction arrows (▸) that animate in and out when processes are active. It's a compact NYX CORE .... ▸ ● ||||| ▸ 2 layout that provides immediate, non-intrusive feedback.

The Debugging Trenches: Lessons Learned the Hard Way

No development session is complete without wrestling with a few stubborn bugs. These moments, while frustrating, often yield the most valuable lessons.

Lesson 1: Taming next/image and Middleware Exclusions

The Problem: I was trying to use next/image to display persona portraits, served from public/images/personas/.

The Attempt: Standard next/image usage.

The Failure: Images failed to load with a mysterious 400 Bad Request error. After some head-scratching and network tab inspection, I realized our authentication middleware was intercepting the internal next/image fetch request for these local assets. It was returning a 307 Redirect to /login, which the image optimizer couldn't handle, leading to the 400.

The Fix & Takeaway: Middleware is powerful, but it needs careful configuration for internal assets. I added images/ to the matcher exclusion in src/middleware.ts.

typescript
// src/middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export async function middleware(req: NextRequest) {
  // ... auth logic ...
  // If not authenticated, redirect to login
  if (!isAuthenticated) {
    return NextResponse.redirect(new URL('/login', req.url));
  }
  return NextResponse.next();
}

export const config = {
  matcher: [
    /*
     * Match all request paths except for the ones starting with:
     * - api (API routes)
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico (favicon file)
     * - images (public images directory) <--- THE FIX
     */
    '/((?!api|_next/static|_next/image|favicon.ico|images).*)',
  ],
};

The Lesson: Always remember that your Next.js middleware runs on every request, including internal asset fetches. Explicitly exclude paths that should bypass authentication or other middleware logic, especially when dealing with public/ assets and next/image.

Lesson 2: Qualifying Ambiguous SQL Columns

The Problem: A complex raw SQL query in src/server/trpc/routers/dashboard.ts was joining workflow_steps and workflows tables.

The Attempt: Referencing output and digest columns directly.

The Failure: PostgreSQL threw a 42702: column reference "output" is ambiguous error. Both workflow_steps and workflows tables happened to have an output column, and the database didn't know which one I meant.

The Fix & Takeaway: When performing joins where multiple tables might share column names, always qualify your column references with the table alias.

sql
-- Before (simplified, problematic)
SELECT output, digest FROM workflow_steps ws JOIN workflows w ON ws.workflow_id = w.id WHERE ...

-- After (simplified, correct)
SELECT ws.output, ws.digest FROM workflow_steps ws JOIN workflows w ON ws.workflow_id = w.id WHERE ...

The Lesson: Ambiguous column references are a classic SQL pitfall. Always use table aliases and qualify your column names in SELECT clauses (and WHERE, ORDER BY, etc.) when joining multiple tables, even if you think there won't be a conflict. It prevents future headaches and makes your queries more robust.

Lesson 3: The Dreaded Nested Button Hydration Error

The Problem: In workflows/[id]/page.tsx, I had an expand/collapse button inside another button (an alternatives card).

The Attempt: <button> inside <button>.

The Failure: React threw a hydration warning: "button cannot be a descendant of button." This isn't just a React warning; it's invalid HTML according to the spec and can lead to accessibility issues and unpredictable behavior.

The Fix & Takeaway: When you need interactive elements nested within other interactive elements (especially buttons), use semantic alternatives.

tsx
// Before (Problematic)
<button onClick={handleOuterClick}>
  Outer Card Action
  <button onClick={handleInnerClick}>Expand/Collapse</button>
</button>

// After (Correct)
<button onClick={handleOuterClick}>
  Outer Card Action
  <span role="button" tabIndex={0} onClick={handleInnerClick}>
    Expand/Collapse
  </span>
</button>

The Lesson: HTML semantics matter, especially for accessibility and browser compatibility. button elements cannot contain other interactive elements like button, a, or input. When you need a clickable region within another interactive element, use a <span> or <div> with role="button" and tabIndex={0} to make it semantically and functionally equivalent, ensuring keyboard navigability.

The Small Victories: Favicons and PWA Icons

Finally, I rounded off the session by ensuring our app feels complete on every platform. I created public/favicon.svg, public/favicon.ico (32px), public/icons/icon-192.png, and public/icons/icon-512.png. These were then added to the icons metadata in src/app/layout.tsx, giving our application a proper PWA experience and a polished look across browsers.

Wrapping Up and Looking Ahead

This marathon session was a microcosm of full-stack development: designing and implementing new features, battling stubborn bugs, and polishing the user experience. It reinforced the importance of meticulous planning, careful debugging, and a deep understanding of the underlying frameworks and languages.

With these changes pushed, the immediate next steps involve thorough QA of the new features (especially the todo importer), reviewing RLS policies, and auditing our safeEnqueue calls for SSE endpoints. The journey continues!

What are some of your recent "marathon session" stories? Share your lessons learned in the comments below!

json
{
  "thingsDone": [
    "Workflow UX improvements (project selector, persona labels)",
    "Todo-to-action-point importer service and UI",
    "Project Reports tab with generation modal",
    "Sidebar heartbeat relayout with animations",
    "NyxCore custom portrait and persona specializations backfill",
    "Middleware image path exclusion for next/image",
    "Dashboard SQL ambiguous column fix",
    "Nested button hydration error fix (span role=button)",
    "Missing favicon/PWA icons added",
    "Structured backlog file created"
  ],
  "pains": [
    "next/image 400 error due to auth middleware interception",
    "PostgreSQL 'column reference is ambiguous' error in raw SQL",
    "React hydration warning 'button cannot be descendant of button'"
  ],
  "successes": [
    "All planned features implemented and typecheck clean",
    "Critical bugs resolved with robust solutions",
    "Improved user experience for workflow creation and project management",
    "Enhanced AI persona utility and visual feedback",
    "Successful implementation of a robust todo-to-action-point import mechanism",
    "Application now has proper PWA icons and favicons"
  ],
  "techStack": [
    "Next.js",
    "React",
    "TypeScript",
    "PostgreSQL",
    "TRPC",
    "Tailwind CSS",
    "SQL (raw queries)",
    "PWA"
  ]
}