claude-code-viewer/docs/dev.md

Developer Documentation

This document provides technical details for developers contributing to Claude Code Viewer.

Architecture Overview

Tech Stack

• Frontend: Next.js 15.5.2 with React 19.1.1, TypeScript with @tsconfig/strictest
• Backend: Hono.js 4.9.5 API routes mounted via Next.js API routes with Zod validation
• Styling: Tailwind CSS 4.1.12 with Radix UI components (shadcn/ui pattern), Geist fonts
• State Management: TanStack Query 5.85.5 + Jotai 2.13.1 atoms with localStorage persistence
• Code Quality: Biome 2.2.2 (replaces ESLint + Prettier completely) with double quotes, 2-space indentation
• Testing: Vitest 3.2.4 with global test setup and watch mode
• Validation: Zod 4.1.5 schemas throughout the stack with modular conversation parsing
• Real-time: Server-Sent Events with FileWatcherService singleton and heartbeat mechanism
• Package Manager: pnpm 10.8.1 with npm-run-all2 for parallel script execution

Project Structure

src/
├── app/                           # Next.js 15 app router
│   ├── api/[[...route]]/         # Hono API mounted via Next.js
│   ├── components/               # App-level components
│   │   ├── ServerEventsProvider.tsx  # SSE connection management
│   │   └── RootErrorBoundary.tsx     # Global error handling
│   ├── projects/                 # Project routes
│   │   ├── [projectId]/         # Dynamic project routes
│   │   │   ├── components/      # Project-specific components
│   │   │   ├── hooks/           # Project data fetching hooks
│   │   │   ├── services/        # Client-side business logic
│   │   │   ├── sessions/        # Session management
│   │   │   │   └── [sessionId]/ # Individual session pages
│   │   │   │       ├── components/ # Session UI components
│   │   │   │       └── hooks/   # Session-specific hooks
│   │   │   └── store/           # Jotai atoms for filtering
│   │   └── components/          # Project list components
│   └── layout.tsx               # Root layout with providers
├── server/                      # Backend implementation
│   ├── hono/                    # Hono.js configuration
│   │   ├── app.ts              # Hono app setup
│   │   └── route.ts            # Route definitions
│   └── service/                 # Core business logic
│       ├── events/              # Real-time event system
│       │   ├── fileWatcher.ts  # File system monitoring
│       │   ├── sseEvent.ts     # SSE event formatting
│       │   └── types.ts        # Event type definitions
│       ├── project/            # Project operations
│       ├── session/            # Session operations
│       ├── parseJsonl.ts       # JSONL parsing logic
│       ├── parseCommandXml.ts  # Command detection
│       └── paths.ts            # File system paths
├── lib/
│   ├── conversation-schema/     # Modular Zod schemas
│   │   ├── content/            # Content type schemas
│   │   ├── entry/              # Entry type schemas
│   │   ├── message/            # Message schemas
│   │   └── tool/               # Tool-specific schemas
│   ├── api/                    # Type-safe API client
│   │   ├── client.ts           # Hono client setup
│   │   └── queryClient.ts      # TanStack Query config
│   ├── sse/                    # SSE client utilities
│   └── utils.ts                # Shared utilities
└── components/
    └── ui/                     # Reusable shadcn/ui components

Development Setup

Prerequisites

• Node.js 18 or later
• pnpm (recommended package manager)
• Claude Code with sample conversation data in ~/.claude/projects/

Installation

git clone https://github.com/d-kimuson/claude-code-viewer.git
cd claude-code-viewer
pnpm install

Development Commands

# Start development server (port 3400 with Turbopack)
pnpm dev        # Runs multiple dev processes in parallel

# Type checking
pnpm typecheck  # TypeScript compilation check

# Code Quality (Biome)
pnpm lint       # Run format and lint checks in sequence
pnpm fix        # Auto-fix format and lint issues (includes unsafe fixes)

# Testing (Vitest)
pnpm test       # Run all tests once
pnpm test:watch # Run tests in watch mode

Build Process

pnpm build      # Next.js standalone build + asset copying

The build process:

1. Creates standalone Next.js build in .next/standalone/
2. Copies public/ assets to standalone directory
3. Copies static assets (.next/static) to standalone directory
4. Results in a fully self-contained application

API Architecture

Hono.js Integration

The backend uses Hono.js mounted via Next.js API routes with a catch-all route at /api/[[...route]]/route.ts. This provides:

• Type-safe API: Full TypeScript inference from server to client
• Zod validation: Request/response validation throughout the stack
• Performance: Lightweight runtime with minimal overhead
• Streaming: Native SSE support for real-time features

API Endpoints

• GET /api/projects - List all projects with metadata
• GET /api/projects/:projectId - Get project details and sessions
• GET /api/projects/:projectId/sessions/:sessionId - Get conversation data
• GET /api/events/state_changes - Server-Sent Events for real-time updates

Data Flow Architecture

File System → Services → Hono Routes → Next.js API → TanStack Query → React Components
     ↓              ↓           ↓             ↓              ↓              ↓
~/.claude/     parseJsonl  route.ts    [[...route]]   useProject    ProjectList
projects/      +schemas    +streaming   /route.ts      +hooks        +components

1. File System Reading: Services read JSONL files from ~/.claude/projects/
2. Schema Validation: Each line validated against modular Zod conversation schemas
3. API Layer: Hono.js routes provide type-safe endpoints with streaming support
4. Client Integration: TanStack Query manages server state with error boundaries
5. Real-time Updates: File watcher emits SSE events, automatically updating UI

Backend Services

Project Services (src/server/service/project/)

• getProjects() - Scans project directories, returns sorted metadata
• getProject(projectId) - Fetches project details and session list
• getProjectMeta(projectId) - Fast metadata extraction

Session Services (src/server/service/session/)

• getSessions(projectId) - List sessions for a project
• getSession(projectId, sessionId) - Parse JSONL conversation files
• getSessionMeta(projectId, sessionId) - Extract session metadata

Event System (src/server/service/events/)

• fileWatcher.ts - FileWatcherService singleton class using Node.js fs.watch()
• sseEvent.ts - Event formatting utilities for SSE
• types.ts - Event type definitions

File Watching Features:

• Monitors ~/.claude/projects/ recursively with singleton pattern
• Event types: connected, project_changed, session_changed, heartbeat
• Heartbeat mechanism (30s intervals) for connection health monitoring
• Automatic cleanup on client disconnection with proper abort handling
• Uses Hono's streamSSE() for efficient server-sent event streaming

Data Validation

Conversation Schema (src/lib/conversation-schema/)

The schema system uses a modular Zod architecture for type-safe conversation parsing:

Schema Organization

conversation-schema/
├── index.ts              # Main union schema
├── content/              # Content type schemas
│   ├── TextContentSchema.ts
│   ├── ToolUseContentSchema.ts
│   ├── ToolResultContentSchema.ts
│   ├── ThinkingContentSchema.ts
│   └── ImageContentSchema.ts
├── entry/                # Entry type schemas
│   ├── BaseEntrySchema.ts
│   ├── UserEntrySchema.ts
│   ├── AssistantEntrySchema.ts
│   ├── SystemEntrySchema.ts
│   └── SummaryEntrySchema.ts
├── message/              # Message schemas
│   ├── UserMessageSchema.ts
│   └── AssistantMessageSchema.ts
└── tool/                 # Tool-specific schemas
    ├── CommonToolSchema.ts
    ├── StructuredPatchSchema.ts
    └── TodoSchema.ts

Key Features

• Union Types: ConversationSchema combines all entry types
• Incremental Parsing: Graceful handling of malformed JSONL lines
• Content Validation: Strict typing for different content formats
• Tool Support: Dedicated schemas for Claude Code tools
• Type Safety: Full TypeScript inference throughout the stack

Command Detection

Advanced XML-like command parsing for enhanced conversation display:

// src/server/service/parseCommandXml.ts
parseCommandXml(content: string) // Extracts command names and arguments

Supports various command formats:

• Slash commands (/save, /edit)
• Local commands with arguments
• Structured command detection for better UX

Frontend Architecture

Component Hierarchy

RootLayout (providers, error boundaries, SSE)
├── ServerEventsProvider (SSE connection management)
├── QueryClientProviderWrapper (TanStack Query setup)
├── RootErrorBoundary (global error handling)
└── Pages
    ├── ProjectList (grid of project cards)
    └── ProjectDetail ([projectId])
        ├── ProjectPage (project overview)
        ├── SessionList (filterable session grid)
        └── SessionDetail ([sessionId])
            ├── SessionPageContent (main layout)
            ├── SessionSidebar (conversation navigation)
            ├── ConversationList (message display)
            ├── ConversationItem (individual messages)
            └── SidechainConversationModal (popup details)

State Management Architecture

Server State (TanStack Query)

• useProjects - Project listing with caching
• useProject - Individual project details and sessions
• useSession - Conversation data fetching
• Suspense Integration: Progressive loading with error boundaries
• Cache Management: Automatic invalidation on SSE events

Client State (Jotai Atoms)

src/app/projects/[projectId]/store/filterAtoms.ts
├── sessionFilterAtom     # Session filtering state
├── searchTermAtom        # Search input state
└── sortOrderAtom         # Session sorting preference

Real-time State (Server-Sent Events)

• useServerEvents - SSE connection hook
• Auto-reconnection: Handles connection drops gracefully
• Event Processing: project_changed, session_changed, heartbeat
• Query Invalidation: Automatic cache refresh on file changes

Type Safety System

• API Types: Full inference from Hono route definitions to React components
• Schema Validation: Runtime and compile-time type checking with Zod
• Build Configuration: @tsconfig/strictest for maximum type safety
• Error Boundaries: Typed error handling throughout the component tree

Hook Patterns

Data Fetching Hooks

// Custom hooks following consistent patterns
useProjects()           // → { data, isLoading, error }
useProject(projectId)   // → { project, sessions, isLoading }
useSession(projectId, sessionId) // → { session, conversations, isLoading }

Real-time Hooks

useServerEvents()       // → SSE connection management
useSidechain()         // → Modal state management

Code Conventions

File Organization Patterns

• Services: Business logic organized by domain (project/, session/, events/)
• Components: Co-located with hooks, stores, and services in feature directories
• Schemas: Modular Zod schemas with clear separation of concerns
• Hooks: Custom hooks grouped by functionality and data dependency
• Types: TypeScript types inferred from Zod schemas where possible

Naming Conventions

• Files: camelCase.ts for most files, PascalCase.tsx for React components
• Components: PascalCase (e.g., SessionPageContent.tsx)
• Functions: camelCase (e.g., getProject, parseJsonl)
• Constants: SCREAMING_SNAKE_CASE (e.g., PROJECTS_BASE_PATH)
• Hooks: use prefix (e.g., useProject, useServerEvents)
• Atoms: Suffix with Atom (e.g., sessionFilterAtom)

Code Style (Biome Configuration)

Biome replaces both ESLint and Prettier with a single, fast tool:

{
  "formatter": {
    "enabled": true,
    "indentStyle": "space"    // 2-space indentation
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "double"  // Double quotes for strings
    }
  },
  "assist": {
    "actions": {
      "source": {
        "organizeImports": "on" // Auto-organize imports
      }
    }
  }
}

Key Style Rules:

• Double quotes for strings
• 2-space indentation
• Automatic import organization
• Biome recommended linting rules
• TypeScript strict mode via @tsconfig/strictest

Development Workflow Integration

# Format and lint check
pnpm lint

# Auto-fix all issues (including unsafe fixes)
pnpm fix

# Type checking
pnpm typecheck

Testing Strategy

Test Structure

• Unit Tests: Individual functions and components
• Integration Tests: API routes and data flow
• Setup: Vitest with global test configuration

Test Commands

pnpm test       # Run all tests once
pnpm test:watch # Watch mode for development

Performance Considerations

Optimization Strategies

• Static Generation: Pre-built project metadata
• Suspense Boundaries: Progressive loading of conversation data
• File Watching: Efficient recursive directory monitoring
• Memory Management: Streaming JSONL parsing for large files

Bundle Analysis

The app uses Next.js with Turbopack for fast development builds and optimized production bundles.

Contributing Guidelines

Pull Request Process

1. Fork the repository and create a feature branch
2. Implement changes following existing code conventions
3. Test your changes with pnpm test
4. Lint code with pnpm fix
5. Type check with pnpm typecheck
6. Submit PR with clear description and test coverage

Code Review Criteria

• Type safety and error handling
• Performance impact on large conversation files
• UI/UX consistency with existing design
• Test coverage for new functionality
• Documentation updates for API changes

Development Tips

• Hot Reload: Use pnpm dev for fast development iteration
• Debug Mode: Enable verbose logging in file watcher service
• Mock Data: Create sample JSONL files for testing edge cases
• Browser DevTools: React Query DevTools available in development

Deployment

Build Artifacts

• Standalone: Self-contained application in .next/standalone/
• Static Assets: Copied to standalone directory during build
• Entry Point: dist/index.js for CLI usage

Environment Variables

• PORT: Server port (default: 3400)
• NODE_ENV: Environment mode (development/production)

The application is designed to be deployed as a standalone executable that can be installed via npm/npx.