mirror of
https://github.com/aljazceru/claude-code-viewer.git
synced 2026-01-07 15:44:21 +01:00
docs: update documents
This commit is contained in:
d-kimsuon
340
docs/dev.md
340
docs/dev.md
@@ -6,34 +6,64 @@ This document provides technical details for developers contributing to Claude C
|
||||
|
||||
### Tech Stack
|
||||
|
||||
- **Frontend**: Next.js 15 with React 19, TypeScript (strict configuration)
|
||||
- **Backend**: Hono.js API routes with Zod validation
|
||||
- **Styling**: Tailwind CSS with Radix UI components (shadcn/ui pattern)
|
||||
- **State Management**: TanStack Query + Jotai atoms
|
||||
- **Code Quality**: Biome (replaces ESLint + Prettier)
|
||||
- **Testing**: Vitest with watch mode
|
||||
- **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
|
||||
|
||||
```text
|
||||
src/
|
||||
├── app/ # Next.js app router
|
||||
│ ├── projects/ # Project listing and detail pages
|
||||
│ │ └── [projectId]/ # Dynamic project routes
|
||||
│ └── layout.tsx # Root layout with providers
|
||||
├── server/ # Backend API implementation
|
||||
│ ├── service/ # Core business logic
|
||||
│ │ ├── file-watcher.ts # Real-time file monitoring
|
||||
│ │ ├── paths.ts # File system path constants
|
||||
│ │ └── project.ts # Project/session operations
|
||||
│ └── api/ # Hono API route handlers
|
||||
├── 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/ # Zod schemas for JSONL validation
|
||||
│ ├── api/ # Type-safe API client
|
||||
│ └── utils/ # Shared utilities
|
||||
│ ├── 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 UI components
|
||||
└── conversation/ # Conversation-specific components
|
||||
└── ui/ # Reusable shadcn/ui components
|
||||
```
|
||||
|
||||
## Development Setup
|
||||
@@ -55,126 +85,278 @@ pnpm install
|
||||
### Development Commands
|
||||
|
||||
```bash
|
||||
# Start development server (port 3400)
|
||||
pnpm dev
|
||||
# Start development server (port 3400 with Turbopack)
|
||||
pnpm dev # Runs multiple dev processes in parallel
|
||||
|
||||
# Type checking
|
||||
pnpm typecheck
|
||||
pnpm typecheck # TypeScript compilation check
|
||||
|
||||
# Linting and formatting
|
||||
pnpm lint # Check all rules
|
||||
pnpm fix # Fix all issues
|
||||
# Code Quality (Biome)
|
||||
pnpm lint # Run format and lint checks in sequence
|
||||
pnpm fix # Auto-fix format and lint issues (includes unsafe fixes)
|
||||
|
||||
# Testing
|
||||
pnpm test # Run once
|
||||
pnpm test:watch # Watch mode
|
||||
# Testing (Vitest)
|
||||
pnpm test # Run all tests once
|
||||
pnpm test:watch # Run tests in watch mode
|
||||
```
|
||||
|
||||
### Build Process
|
||||
|
||||
```bash
|
||||
pnpm build # Creates standalone Next.js build in .next/standalone/
|
||||
pnpm build # Next.js standalone build + asset copying
|
||||
```
|
||||
|
||||
The build creates a standalone application that includes all dependencies for deployment.
|
||||
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
|
||||
|
||||
### Endpoints
|
||||
### 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
|
||||
### Data Flow Architecture
|
||||
|
||||
1. **File System → Parser**: Read JSONL files from `~/.claude/projects/`
|
||||
2. **Parser → Validation**: Validate each line against Zod conversation schemas
|
||||
3. **API → Frontend**: Type-safe data transfer with TanStack Query
|
||||
4. **Real-time**: File watcher emits SSE events for live updates
|
||||
```text
|
||||
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
|
||||
|
||||
#### Core Services (`src/server/service/`)
|
||||
#### Project Services (`src/server/service/project/`)
|
||||
|
||||
- **`getProjects()`** - Scans project directories, returns sorted metadata
|
||||
- **`getProject(projectId)`** - Fetches project details and session list
|
||||
- **`getSession(projectId, sessionId)`** - Parses JSONL conversation files
|
||||
- **`parseJsonl()`** - Validates JSONL lines against conversation schema
|
||||
- **`getProjectMeta(projectId)`** - Fast metadata extraction
|
||||
|
||||
#### File Watching (`src/server/service/file-watcher.ts`)
|
||||
#### Session Services (`src/server/service/session/`)
|
||||
|
||||
- Singleton service using Node.js `fs.watch()`
|
||||
- Monitors `~/.claude/projects/` recursively
|
||||
- Emits `project_changed` and `session_changed` events
|
||||
- Includes heartbeat mechanism (30s intervals)
|
||||
- **`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/`)
|
||||
|
||||
Modular Zod schemas handle different conversation entry types:
|
||||
The schema system uses a modular Zod architecture for type-safe conversation parsing:
|
||||
|
||||
- **Entry Types**: User, Assistant, System, Summary
|
||||
- **Content Types**: Text, Tool Use, Tool Result, Thinking
|
||||
- **Validation**: Strict type checking with fallback parsing
|
||||
#### Schema Organization
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
Special XML-like command parsing for enhanced display:
|
||||
Advanced XML-like command parsing for enhanced conversation display:
|
||||
|
||||
```typescript
|
||||
// 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
|
||||
|
||||
```text
|
||||
RootLayout (providers, error boundaries)
|
||||
├── ProjectList (grid of project cards)
|
||||
├── ProjectDetail
|
||||
│ ├── SessionList (filterable session grid)
|
||||
│ └── SessionDetail
|
||||
│ ├── SessionSidebar (navigation)
|
||||
│ └── ConversationList (message display)
|
||||
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
|
||||
### State Management Architecture
|
||||
|
||||
- **Server State**: TanStack Query with suspense boundaries
|
||||
- **Client State**: Jotai atoms for UI state (filters, sidebar state)
|
||||
- **Real-time**: Server-Sent Events with automatic reconnection
|
||||
#### 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
|
||||
|
||||
### Type Safety
|
||||
#### Client State (Jotai Atoms)
|
||||
```text
|
||||
src/app/projects/[projectId]/store/filterAtoms.ts
|
||||
├── sessionFilterAtom # Session filtering state
|
||||
├── searchTermAtom # Search input state
|
||||
└── sortOrderAtom # Session sorting preference
|
||||
```
|
||||
|
||||
- **API Types**: Generated from Hono route definitions
|
||||
- **Schemas**: Zod validation with TypeScript inference
|
||||
- **Build-time**: Strict TypeScript configuration via `@tsconfig/strictest`
|
||||
#### 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
|
||||
```typescript
|
||||
// Custom hooks following consistent patterns
|
||||
useProjects() // → { data, isLoading, error }
|
||||
useProject(projectId) // → { project, sessions, isLoading }
|
||||
useSession(projectId, sessionId) // → { session, conversations, isLoading }
|
||||
```
|
||||
|
||||
#### Real-time Hooks
|
||||
```typescript
|
||||
useServerEvents() // → SSE connection management
|
||||
useSidechain() // → Modal state management
|
||||
```
|
||||
|
||||
## Code Conventions
|
||||
|
||||
### File Organization
|
||||
### File Organization Patterns
|
||||
|
||||
- **Services**: Business logic in `src/server/service/`
|
||||
- **Components**: UI components with co-located styles
|
||||
- **Schemas**: Modular Zod schemas with clear interfaces
|
||||
- **Hooks**: Custom hooks for data fetching and state management
|
||||
- **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**: `kebab-case.ts`
|
||||
- **Components**: `PascalCase`
|
||||
- **Functions**: `camelCase`
|
||||
- **Constants**: `SCREAMING_SNAKE_CASE`
|
||||
- **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
|
||||
### Code Style (Biome Configuration)
|
||||
|
||||
- **Formatter**: Biome (replaces Prettier)
|
||||
- **Linter**: Biome (replaces ESLint)
|
||||
- **Config**: Extends `@tsconfig/strictest` for maximum type safety
|
||||
**Biome replaces both ESLint and Prettier** with a single, fast tool:
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```bash
|
||||
# Format and lint check
|
||||
pnpm lint
|
||||
|
||||
# Auto-fix all issues (including unsafe fixes)
|
||||
pnpm fix
|
||||
|
||||
# Type checking
|
||||
pnpm typecheck
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
|
||||
Reference in New Issue
Block a user