Crafting a Developer's Second Brain: Lessons from Building Our AI-Powered Project Insight System

As developers, we're constantly building, iterating, and learning. But how often do we truly capture and leverage those fleeting insights, the 'aha!' moments, the stubborn bugs, and their hard-won solutions? Our latest project aims to solve just that: an AI-powered developer memory system that transforms raw development sessions into structured knowledge.

This post serves as a high-level session handoff, a snapshot of where we are, what we've built, and, crucially, the lessons we've learned along the way. We're on the cusp of rolling out a powerful "Consolidation" feature, but before we dive into that, let's anchor ourselves in the foundation we've laid.

The Foundation: From GitHub to AI-Generated Blogs

Our core pipeline is now robustly in place. We've established a seamless flow that takes your GitHub activity, processes it, and generates insightful blog posts or "memory fragments."

Here’s a quick rundown of the essential components that are now live, committed, and pushed to origin/main:

• Data Models with Prisma: We’re using Prisma for our ORM, defining Project and BlogPost models. These are carefully structured with tenant and user relations to ensure data isolation and ownership.
• GitHub Integration (src/server/services/github-connector.ts): A custom, BYOK (Bring Your Own Key) GitHub implementation allows us to securely connect to repositories, fetch commit history, and pull relevant code snippets and commit messages. This is the raw material for our memory system.
• AI-Powered Blog Generation (src/server/services/blog-generator.ts): The heart of the intelligence. This TypeScript port of our initial blog_gen.py prompt takes the raw GitHub data and, using a sophisticated AI model, crafts coherent and insightful blog posts. It’s designed to extract the narrative from the code.
• Robust tRPC Routers (src/server/trpc/routers/projects.ts): Our backend API is built with tRPC, offering end-to-end type safety. The projects router handles all CRUD operations for projects, manages GitHub integrations, and orchestrates blog post generation.
• Rich Markdown Rendering (src/components/markdown-renderer.tsx): On the frontend, we're using react-markdown with remark-gfm to beautifully render the AI-generated content, complete with GitHub Flavored Markdown support.
• Intuitive User Interface: We've built out four key pages: a projects list, a new project creation flow, a detailed project view (with tabs for different insights), and a dedicated blog post viewer. Navigation is smooth, handled by a sidebar for desktop and a mobile bottom nav.
• Interactive Generation Flow: Users can generate single posts sequentially with live progress updates, or use our "Generate More" sheet for batch operations, allowing selection of multiple files and displaying content length previews.

The Next Frontier: Consolidation

With the core pipeline humming, our next big undertaking is the "Consolidation" feature. Imagine having a decade of your development work across various projects, distilled into actionable insights. That's the goal.

This feature will:

• Accumulate Cross-Project Knowledge: Gather all generated letters/blog posts from across various projects.
• AI-Powered Pattern Extraction: Our AI will go beyond single-post generation to identify overarching patterns – recurring successes, persistent pain points, and common solutions – across your entire development history.
• Searchable Overview: Provide a powerful, searchable interface to explore these extracted patterns and consolidated knowledge.
• Prompt-Hint Export: Generate tailored prompts or hints that you can use in your daily workflow, whether it's for starting a new project, debugging a familiar error, or planning a complex feature.
• Workflow Integration: Seamlessly integrate these insights into your existing development workflow.

Navigating the Treacherous Waters: Lessons Learned (The Pain Log)

Building a system like this isn't without its challenges. Here are some critical lessons we've learned during this sprint, particularly around our Next.js, tRPC, and React Query stack:

1. React Query refetch() on Disabled Queries

The Pain: We noticed queryClient.refetchQueries() was unreliable for queries that were initially disabled. It wouldn't always trigger a fetch, leading to stale data or unexpected behavior.

The Lesson: For queries that need to be conditionally fetched, especially after an action, always control their execution via the enabled flag, driven by component state, rather than relying solely on refetch().

// Less reliable:
const { data, refetch } = trpc.projects.getProject.useQuery(
  { id },
  { enabled: false } // Initial state
);

// Somewhere later:
// refetch(); // Might not work as expected if 'enabled' is false

// More reliable:
const [shouldFetch, setShouldFetch] = useState(false);
const { data } = trpc.projects.getProject.useQuery(
  { id },
  { enabled: shouldFetch }
);

// Somewhere later, after an action:
setShouldFetch(true); // This will trigger the query

2. Batch Mutations vs. UI Progress

The Pain: When performing batch mutations (e.g., generating multiple blog posts), a single server-side call meant there was no granular mid-mutation progress feedback to the user. The UI would just hang until the entire batch was complete.

The Lesson: For a better user experience, especially with long-running operations, break down batch mutations into sequential client-side calls. This allows you to update the UI after each individual item in the batch completes, providing live progress and a more responsive feel. This might mean more network requests, but the UX gain is often worth it.

3. The .next Cache and Prisma Schema Changes

The Pain: Modifying the Prisma schema (schema.prisma) sometimes led to frustrating errors or stale client definitions, even after running prisma generate. The .next cache seemed to hold onto old types.

The Lesson: When making Prisma schema changes:

1. Stop your Next.js development server FIRST.
2. Delete the .next directory.
3. Run prisma generate.
4. Restart your Next.js development server. This ensures a clean slate and that your Prisma client and Next.js's internal caches are in sync.

4. TypeScript Inference with tRPC and React Query

The Pain: We encountered situations where ReturnType<typeof trpc...useQuery> would incorrectly resolve the data property as {} (an empty object type), losing the rich type inference tRPC is known for.

The Lesson: While tRPC's inference is usually stellar, for complex queries or when facing this specific issue, explicitly define your data interfaces. This ensures type safety and clarity, even if it means a little more boilerplate.

// Less reliable inference:
// const { data } = trpc.projects.getProject.useQuery({ id });
// data might be inferred as {}

// More robust:
interface ProjectDetail {
  id: string;
  name: string;
  // ... other project properties
}

const { data } = trpc.projects.getProject.useQuery<ProjectDetail>({ id });
// Now 'data' is guaranteed to be ProjectDetail | undefined

5. Tailwind Typography require() vs. ESM import

The Pain: Integrating @tailwindcss/typography into tailwind.config.ts initially caused issues because we were using require() for the plugin, which conflicts with the ESM context of a TypeScript config file.

The Lesson: In modern Next.js/Tailwind setups, especially with .ts config files, use ESM import statements for your Tailwind plugins.

// tailwind.config.ts
import type { Config } from 'tailwindcss';
import typography from '@tailwindcss/typography'; // <-- Use import

const config: Config = {
  content: [
    // ...
  ],
  theme: {
    extend: {
      // ...
    },
  },
  plugins: [typography], // <-- Add the imported plugin
};

export default config;

Looking Ahead: The Road to Consolidation

Our immediate next steps are focused squarely on bringing the Consolidation feature to life:

1. Research & Requirements: Deep dive into the codebase to fully map out consolidation requirements.
2. Prisma Schema Design: Architect the new Consolidation model and its relationships (likely many-to-many with projects).
3. AI Pattern Extraction Service: Design and implement the sophisticated AI service responsible for identifying cross-project patterns.
4. Consolidation tRPC Router: Build the backend API for managing consolidated insights.
5. Searchable Overview Page: Develop the frontend page to display and filter these consolidated insights.
6. Prompt-Hint Export: Implement the functionality to generate and export actionable prompts.
7. Workflow Integration: Connect the new feature into our existing workflow page.

This project is a journey into making developers' lives easier and more insightful. We're excited about the potential of the Consolidation feature to truly transform how we learn from our own work. Stay tuned for more updates as we continue to build out this developer's second brain!

{
  "thingsDone": [
    "Prisma schema: Project + BlogPost models with tenant/user relations",
    "src/server/services/github-connector.ts – full BYOK GitHub implementation",
    "src/server/services/blog-generator.ts – TypeScript port of blog_gen.py prompt",
    "src/server/trpc/routers/projects.ts – full router (CRUD, github, blogPosts)",
    "src/components/markdown-renderer.tsx – react-markdown + remark-gfm",
    "4 pages: projects list, new project, project detail (tabbed), blog post viewer",
    "Navigation: Projects in sidebar + mobile bottom nav",
    "Sequential single-post generation with live progress",
    "Generate More sheet with select-all, filenames, content length"
  ],
  "pains": [
    "tRPC + React Query v5: refetch() on disabled queries is unreliable",
    "Batch mutations: No mid-mutation progress",
    ".next cache: Must stop dev server FIRST before deleting .next, then prisma generate after schema changes",
    "TypeScript inference: ReturnType<typeof trpc...useQuery> resolves data as {}",
    "Tailwind typography: require() → ESM import in tailwind.config.ts"
  ],
  "successes": [
    "Robust GitHub integration for data ingestion",
    "Effective AI-powered blog generation from commit data",
    "Type-safe API with tRPC across frontend and backend",
    "Smooth markdown rendering for generated content",
    "Intuitive UI for project management and content generation",
    "Clear understanding and resolution of common Next.js/React Query/tRPC pitfalls"
  ],
  "techStack": [
    "Next.js",
    "tRPC",
    "React Query v5",
    "Prisma",
    "TypeScript",
    "GitHub API",
    "react-markdown@^9",
    "remark-gfm@^4",
    "@tailwindcss/typography@^0.5",
    "Tailwind CSS"
  ]
}