Claude Code Memory Bank

Purpose: This document serves as a persistent memory for Claude Code sessions, providing context about the project, recent work, and important patterns to follow.

Maintenance: When completing significant work, update the "Recent Updates" section with a dated entry. Archive entries older than 3 months to the bottom of the file.

Design Context

Users

Primary audience: Engineering peers and the technical community—fellow engineers, CTOs, and technical leaders who appreciate craft and thoughtful problem-solving. Visitors arrive to evaluate Brennan's work, learn from his writing on engineering leadership and value-based care, or explore his photography. They expect a site that reflects the same care and attention to detail they'd expect in well-architected software.

Brand Personality

Voice: Direct but warm. Explains complex ideas clearly without being condescending. Shares openly about challenges and learnings.

Tone: Reflective and substantive—prioritizes depth over polish, insight over self-promotion.

Three words: Thoughtful, Builder, Curious

Emotional goals: Visitors should feel that Brennan is approachable and thoughtful ("I'd like to work with or learn from this person") and creative/distinctive ("This person thinks differently and has taste").

Aesthetic Direction

Visual tone: Sophisticated minimalism with warmth. The current "Slate Executive" palette (cool mist backgrounds, steel blue and dusty teal accents, warm copper CTAs) establishes a calm, professional foundation while the serif typography (EB Garamond) and subtle texture add personality.

Current design language:

Full-bleed sections with semi-transparent backgrounds reveal floating particles beneath
Work cards with hover states create tactile, interactive feel
Section labels in small caps + elegant serif italic headings establish hierarchy
Generous whitespace and 680px content width prioritize readability

Theme: Light mode only (current implementation)

Colors in use:

Token	Value	Usage
Background	`#f0f2f5`	Cool Mist - page background
Foreground	`#2c333a`	Deep Charcoal Blue - body text
Primary	`#5a7684`	Steel Blue - headers, branding
Accent	`#749ca8`	Dusty Teal - links, borders
Accent Bold	`#c17f59`	Warm Copper - CTAs, emphasis
Muted	`#e8eaed` / `#5a6570`	Subtle backgrounds, secondary text

Design Principles

Clarity over cleverness: Every design choice should make content easier to consume, not harder. Typography, spacing, and visual hierarchy serve readability first.
Warmth within professionalism: Balance the cool, sophisticated palette with warm touches—the copper accent, the serif italics, the subtle texture—that make the site feel human and inviting.
Craft reflects craft: The site should demonstrate the same attention to detail and quality that Brennan brings to engineering work. Small refinements matter.
Content breathes: Generous whitespace, constrained content width, and clear section boundaries let the writing and photography take center stage.
Accessible by default: WCAG 2.1 AA compliance, reduced motion support, semantic markup. Good design works for everyone.

Project Overview

Tech Stack (Current)

Component	Version	Notes
Next.js	16.1.1	Turbopack default, async route params
React	19.2.3	Using automatic JSX runtime
TypeScript	5.9.3	Strict mode enabled
Notion Client	5.6.0	Uses dataSources API (not databases)
Tailwind CSS	4.1.18	v4 with Lightning CSS
Vitest	4.0.16	Test runner with Istanbul coverage
ESLint	9.39.2	Flat config format (eslint.config.mjs)

Project Statistics

Tests: 132 tests (2 skipped)
Build Time: ~21s (production static build)
Pages: 34 static pages
Node Version: 24.x

Architecture

Type: Static site generation with Astro
CMS: Notion as headless CMS via Content Collections
Deployment: Cloudflare Pages
Sections: "All" (general posts) and "VBC" (Value-Based Care series)
Images: Local images in public/images/

Key Patterns & Conventions

Development Workflow

Testing First: Run tests before any changes (npm test)
Type Safety: Verify TypeScript compilation (npm run typecheck)
Build Verification: Test production builds after major changes (npm run build)
Feature Branches: Use descriptive branch names (e.g., upgrade/nextjs-16, feature/json-feed)

Code Patterns

Notion API Usage

// ✅ Correct (v5.x API)
await notion.dataSources.query({
  data_source_id: NOTION_DATABASE_ID,
  // ...
});

// ❌ Incorrect (old v4.x API)
await notion.databases.query({
  database_id: NOTION_DATABASE_ID,
  // ...
});

Async Route Params (Next.js 16+)

// ✅ Correct (Next.js 16 requires Promise)
interface PageProps {
  params: Promise<{ slug: string }>;
}

export default async function Page({ params }: PageProps) {
  const { slug } = await params;
  // ...
}

Image Configuration

// Required in next.config.ts for custom quality values
images: {
  qualities: [75, 85],  // Must list all quality values used
  formats: ['image/webp', 'image/avif'],
  // ...
}

ESLint Configuration (v9 Flat Config)

// eslint.config.mjs - ESLint v9 uses flat config format
import nextPlugin from 'eslint-config-next';

const eslintConfig = [
  {
    ignores: ['.next/**', 'node_modules/**', 'coverage/**'],
  },
  ...nextPlugin,
  {
    rules: {
      '@typescript-eslint/no-require-imports': 'off',
    },
  },
  {
    files: ['**/__tests__/**/*.ts', '**/__tests__/**/*.tsx'],
    rules: {
      '@typescript-eslint/no-explicit-any': 'off',
    },
  },
];

export default eslintConfig;

Note: ESLint v9 requires flat config format. Legacy .eslintrc.json files are no longer supported.

Testing Patterns

Vitest: Test runner with global imports configured
React Testing Library: Behavioral testing, avoid implementation details
Mocking: Use vi.mocked() for type-safe mocks
Snapshots: Update with npm test -- -u after intentional changes
Timezone Handling: Use regex for date assertions (e.g., /Aug (19|20), 2023/)

File Locations

Purpose	Location	Example
Components	`src/components/`	`post-card.tsx`
API Routes	`src/app/*/route.ts`	`feed.json/route.ts`
Utilities	`src/lib/`	`notion.ts`, `config.ts`
Tests	`__tests__/`	`__tests__/lib/notion.test.ts`
Scripts	`scripts/`	`cache-posts.ts`
Documentation	`docs/`	`*.md` files
Config	Root directory	`eslint.config.mjs`, `next.config.ts`

Commands Reference

# Development
npm run dev              # Start dev server (Turbopack HMR)
npm run build            # Production build
npm run cache:posts      # Fetch & cache posts from Notion

# Testing
npm test                 # Run all tests
npm run test:watch       # Watch mode
npm run test:coverage    # Coverage report
npm run test:ui          # Vitest UI

# Quality Checks
npm run typecheck        # TypeScript validation
npm run lint             # ESLint

Recent Updates

Note: Keep high-level summaries here. Link to detailed docs in /docs for full context.

Archive Policy: Move entries older than 3 months to the "Archive" section at the bottom.

December 2025 Work Summary

Visual Theme Overhaul (PR #872):

✅ Redesigned homepage layout with improved visual hierarchy
✅ Updated footer design with better spacing and styling
✅ Enhanced particle animation system with theme-aware colors
✅ Improved table of contents component styling
✅ Refreshed post layout and VBC footer components
✅ Added 190+ lines of new CSS utilities in globals.css

Floating Particles Optimization:

✅ Disabled particle background on mobile browsers (viewport < 768px)
✅ Uses existing useIsMobile hook for responsive detection
✅ Improves mobile performance by skipping animation entirely

Infrastructure:

✅ Added GitHub Actions workflow for Claude Code (.github/workflows/claude.yml)
✅ Updated all dependencies to latest versions
✅ Node.js 24.x support confirmed

Key Metrics:

Tests: 132 passing
All dependencies current
4 low severity vulnerabilities (acceptable)

January 2026 - Astro Migration:

✅ Migrated from Next.js to Astro 5
✅ Deployed to Cloudflare Pages (was Vercel)
✅ Content Collections with custom Notion loader
✅ React islands for interactive components

Troubleshooting & Known Issues

Common Issues

Notion API Errors

Ensure using dataSources.query() not databases.query() (v5+ API)
Verify data_source_id is correct in environment variables
Check API version is compatible (default 2025-09-03 works)

Test Failures

Date assertions: Use regex for timezone variations (e.g., /Aug (19|20), 2023/)
Snapshot mismatches: Review changes, update with npm test -- -u if intentional
Mock errors: Use vi.mocked() for type-safe mocking

Quick Reference

Environment Variables Required

NOTION_TOKEN=secret_xxx                    # Notion API integration token
NOTION_POSTS_DATABASE_ID=xxx               # Posts database/datasource ID
NOTION_PHOTOS_DATABASE_ID=xxx              # Photos database/datasource ID
SITE_URL=https://brennanmoore.com          # Site URL for absolute links

Project Structure

homepage-notion-nextjs/
├── src/
│   ├── app/                    # Next.js 16 App Router
│   │   ├── (routes)/          # Page routes
│   │   ├── feed.json/         # JSON Feed route
│   │   ├── rss.xml/           # RSS feed route
│   │   └── sitemap.xml/       # Dynamic sitemap
│   ├── components/            # React components
│   ├── lib/                   # Utilities (notion, config, errors)
│   └── styles/                # Tailwind CSS
├── __tests__/                 # Vitest tests
├── scripts/                   # Build scripts (cache-posts.ts)
├── docs/                      # Project documentation
├── posts-cache.json          # Cached posts from Notion
├── photos-cache.json         # Cached photos from Notion
└── public/images/            # Optimized images

Last Updated: 2025-12-28 Document Version: 2.2 (December 2025 visual theme + mobile particle optimization)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Claude Code Memory Bank

Design Context

Users

Brand Personality

Aesthetic Direction

Design Principles

Project Overview

Tech Stack (Current)

Project Statistics

Architecture

Key Patterns & Conventions

Development Workflow

Code Patterns

Notion API Usage

Async Route Params (Next.js 16+)

Image Configuration

ESLint Configuration (v9 Flat Config)

Testing Patterns

File Locations

Commands Reference

Recent Updates

December 2025 Work Summary

Troubleshooting & Known Issues

Common Issues

Archive

October 2025 Work Summary (Archived)

ESLint v9 & Dependency Updates - Completed

Test Coverage Improvement - Completed

Image Optimization Implementation - Completed

JSON Feed and Schema.org JSON-LD Enhancement - Completed

Code Quality Improvements - Completed

@notion/client Migration (v4.0.2 → v5.1.0) - Completed

Quick Reference

Environment Variables Required

Project Structure

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

Claude Code Memory Bank

Design Context

Users

Brand Personality

Aesthetic Direction

Design Principles

Project Overview

Tech Stack (Current)

Project Statistics

Architecture

Key Patterns & Conventions

Development Workflow

Code Patterns

Notion API Usage

Async Route Params (Next.js 16+)

Image Configuration

ESLint Configuration (v9 Flat Config)

Testing Patterns

File Locations

Commands Reference

Recent Updates

December 2025 Work Summary

Troubleshooting & Known Issues

Common Issues

Archive

October 2025 Work Summary (Archived)

ESLint v9 & Dependency Updates - Completed

Test Coverage Improvement - Completed

Image Optimization Implementation - Completed

JSON Feed and Schema.org JSON-LD Enhancement - Completed

Code Quality Improvements - Completed

@notion/client Migration (v4.0.2 → v5.1.0) - Completed

Quick Reference

Environment Variables Required

Project Structure