mirror of
https://github.com/aljazceru/claude-code-viewer.git
synced 2025-12-23 08:14:21 +01:00
9749a7e02b
- Updated the Node.js version in .node-version and package.json to 20.19.0. - Revised README.md and docs/dev.md to reflect the new minimum Node.js requirement. - Adjusted setup-node action to use the version specified in .node-version for consistency.
206 lines
6.7 KiB
Markdown
206 lines
6.7 KiB
Markdown
# Developer Documentation
|
|
|
|
This document provides technical details for developers contributing to Claude Code Viewer.
|
|
|
|
## Architecture Overview
|
|
|
|
### Frontend
|
|
|
|
- **Framework**: Next.js 15 (App Router)
|
|
- **UI Libraries**: React 19, Radix UI, Tailwind CSS
|
|
- **State Management**: Jotai (global state), TanStack Query (server state)
|
|
|
|
### Backend
|
|
|
|
- **API Framework**: Hono integrated with Next.js API Routes
|
|
- Type-safe communication via Hono RPC
|
|
- Validation using `@hono/zod-validator`
|
|
- **Effect-TS**: All backend business logic is implemented using Effect-TS
|
|
- Service layer managed through Effect Context (dependency injection container)
|
|
- Controller → Service layered architecture, with each layer implemented in Effect
|
|
- Type-safe error handling and side effect control
|
|
|
|
### Data Source and Storage
|
|
|
|
- **Single Source of Truth (SSoT)**: Claude Code's standard session logs (`~/.claude/projects/`)
|
|
- No separate database; reads directly from JSONL files
|
|
- Strict validation via Zod schemas ensures conversation data integrity
|
|
- **Caching Mechanism**: For performance optimization, metadata is cached in `~/.claude-code-viewer/`
|
|
- Frequently accessed data like session lists and project information
|
|
- Cache is automatically invalidated via SSE events
|
|
|
|
### Real-time Synchronization
|
|
|
|
- **Server-Sent Events (SSE)**: Provides `/api/sse` endpoint
|
|
- Clients maintain persistent SSE connections to listen for server events
|
|
- Real-time delivery of session log updates, process state changes, etc.
|
|
- Type-safe SSE events (`TypeSafeSSE`) guarantee payload types for each event kind
|
|
- Client-side easily subscribes to events using the `useServerEventListener` hook
|
|
|
|
### Session Process Management
|
|
|
|
Claude Code Viewer provides advanced control over Claude Code session processes:
|
|
|
|
- After starting a session, the process remains in the background unless explicitly aborted
|
|
- Paused sessions can continue without changing the session-id (no resume needed)
|
|
- Memory sharing between processes is required, making production build verification crucial
|
|
|
|
## Development Environment Setup
|
|
|
|
### Requirements
|
|
|
|
- **Node.js**: Version 20.19.0 or later (see [.node-version](../.node-version))
|
|
- **Package Manager**: pnpm 10.8.1 or later
|
|
|
|
### Initial Setup
|
|
|
|
```bash
|
|
# Install dependencies
|
|
pnpm install
|
|
```
|
|
|
|
## Starting the Development Server
|
|
|
|
### Development Mode (with limitations)
|
|
|
|
```bash
|
|
pnpm dev
|
|
```
|
|
|
|
The development server will start, but **with the following limitations**:
|
|
|
|
#### Next.js Development Server Constraints
|
|
|
|
The Next.js development server behaves like an Edge Runtime where API Routes don't share memory space. This causes:
|
|
|
|
1. **Initialization runs on every request**: Initialization occurs for each API request, degrading performance
|
|
2. **Session process continuation unavailable**: Cannot resume Paused sessions across different requests
|
|
3. **SSE connection and process management inconsistencies**: Events that should be notified via SSE aren't shared between processes
|
|
|
|
Therefore, **development mode is sufficient for UI verification and minor changes**, but **production build startup is essential for comprehensive testing of session process management and SSE integration**.
|
|
|
|
### Production Mode (Recommended)
|
|
|
|
For comprehensive functionality testing, build and run in production mode:
|
|
|
|
```bash
|
|
# Build
|
|
pnpm build
|
|
|
|
# Start production server
|
|
pnpm start
|
|
```
|
|
|
|
The built application is output to the `dist/` directory and started with `pnpm start`.
|
|
|
|
## Quality Assurance
|
|
|
|
### Code Formatter & Linter: Biome
|
|
|
|
[Biome](https://biomejs.dev/) is used as the formatter and linter.
|
|
|
|
**Commands**:
|
|
|
|
```bash
|
|
# Auto-fix issues
|
|
pnpm fix
|
|
|
|
# Check only (run in CI)
|
|
pnpm lint
|
|
```
|
|
|
|
**CI Requirement**: Passing Biome checks is mandatory for PR merges.
|
|
|
|
### Unit Tests: Vitest
|
|
|
|
Vitest-based tests are written for backend core logic (Effect-TS based service layer).
|
|
|
|
**Commands**:
|
|
|
|
```bash
|
|
# Run once
|
|
pnpm test
|
|
|
|
# Watch mode
|
|
pnpm test:watch
|
|
```
|
|
|
|
**Test Coverage**: Primarily business logic under `src/server/core/`
|
|
|
|
**CI Requirement**: All tests must pass for PR merges.
|
|
|
|
### Type Checking: TypeScript
|
|
|
|
```bash
|
|
pnpm typecheck
|
|
```
|
|
|
|
Strict type configuration (`@tsconfig/strictest`) is adopted, emphasizing type safety.
|
|
|
|
### E2E Snapshot Testing (VRT)
|
|
|
|
Playwright-based snapshot capture is implemented to visually confirm UI changes.
|
|
|
|
**Note**: This is Visual Regression Testing (VRT) for confirming UI changes, not traditional testing.
|
|
|
|
#### Local Execution
|
|
|
|
```bash
|
|
# Run server startup and snapshot capture together
|
|
pnpm e2e
|
|
|
|
# Or execute manually
|
|
pnpm e2e:start-server # Start server
|
|
pnpm e2e:capture-snapshots # Capture snapshots
|
|
```
|
|
|
|
**Important**: In local environments, UI varies based on the current path. **Do not commit locally captured snapshots**.
|
|
|
|
#### Automatic Updates in CI
|
|
|
|
When the `vrt` label is added to a PR, CI automatically captures and commits snapshots. Use this label for PRs with UI changes to update snapshots.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
├── app/ # Next.js App Router
|
|
│ ├── api/[[...route]]/ # Hono API Routes
|
|
│ ├── components/ # Page-specific components
|
|
│ ├── projects/ # Project-related pages
|
|
│ └── ...
|
|
├── components/ # Shared UI components
|
|
├── lib/ # Frontend common logic
|
|
│ ├── api/ # API client (Hono RPC)
|
|
│ ├── sse/ # SSE connection management
|
|
│ └── conversation-schema/ # Zod schemas for conversation logs
|
|
├── server/ # Backend implementation
|
|
│ ├── core/ # Core domain logic (Effect-TS)
|
|
│ │ ├── claude-code/ # Claude Code integration
|
|
│ │ ├── events/ # SSE event management
|
|
│ │ ├── session/ # Session management
|
|
│ │ └── ...
|
|
│ ├── hono/ # Hono application
|
|
│ └── lib/ # Backend common utilities
|
|
└── testing/ # Test helpers and mocks
|
|
```
|
|
|
|
## Development Tips
|
|
|
|
1. **Learning Effect-TS**: The backend is built with Effect-TS. Refer to the [official documentation](https://effect.website/)
|
|
2. **Debugging SSE**: Check the Network tab in browser developer tools to inspect SSE connections
|
|
3. **Log Inspection**: Directly reference JSONL files under `~/.claude/projects/` to understand data structures
|
|
4. **Mock Data**: Mock data for E2E tests in `mock-global-claude-dir/` is useful for development reference
|
|
|
|
## Contributing
|
|
|
|
We welcome contributions! Please:
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes with appropriate tests
|
|
4. Ensure all quality checks pass (`pnpm lint`, `pnpm test`, `pnpm typecheck`)
|
|
5. Submit a pull request with a clear description of your changes
|
|
|
|
For UI changes, add the `vrt` label to your PR to update visual snapshots.
|