# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**Warpgate** is an SSD read-write caching proxy that accelerates remote NAS access for photographers, videographers, and remote workers. It sits between client devices and a remote NAS, providing local SSD caching with automatic write-back.

- **Current state**: Specification/PRD only (`warpgate-prd-v4.md`, written in Chinese). No implementation code exists yet.
- **MVP target**: Configuration files + bash deployment scripts for Linux (Ubuntu 22.04+ / Debian 12+)
- **Primary user**: Photographers using Lightroom over Tailscale to access a home NAS

## Architecture

```
Clients (macOS/Windows/Linux/iPad)
  │  SMB / NFS / WebDAV
  ▼
Warpgate Proxy (local network)
  ├─ Samba Server (SMB2/3 — primary, for Lightroom/Finder/Explorer)
  ├─ NFS Server (Linux clients)
  ├─ WebDAV Server (mobile)
  └─ rclone VFS FUSE mount (/mnt/nas-photos)
       └─ SSD Cache (rclone-managed LRU, dirty file protection)
            │  SFTP over Tailscale/WireGuard
            ▼
       Remote NAS (any brand supporting SFTP)
```

**Key design decisions:**
- All protocols share a single rclone FUSE mount point — one cache layer, no duplication
- rclone VFS with `--vfs-cache-mode full` handles both read-through caching and async write-back
- **Single-direction write constraint**: NAS doesn't change while user is away, eliminating conflict resolution
- Remote change detection uses rclone's `--dir-cache-time` (no brand-specific NAS APIs)
- Cache filesystem should be btrfs or ZFS (CoW + journal for crash consistency)

## Core Technologies

- **rclone** v1.65+ — VFS FUSE mount, read-through cache, async write-back, LRU eviction, RC API
- **Samba** 4.x — SMB shares for macOS/Windows clients
- **nfs-kernel-server** — NFS exports for Linux clients
- **FUSE** 3.x — userspace filesystem for rclone mount
- **Tailscale/WireGuard** — secure tunnel to remote NAS via SFTP

## PRD Structure (warpgate-prd-v4.md)

The PRD is comprehensive (836 lines, Chinese) with these sections:
- Sections 1-2: Product positioning, target users
- Section 3: System architecture with Mermaid diagrams
- Section 4: Features organized by priority (P0=MVP, P1=important, P2=future)
- Section 5: Data consistency model and scenario walkthroughs
- Sections 6-7: Remote change detection, cache behavior details
- Section 8: Full configuration parameter reference
- Section 9: Preset templates (photographer, video editor, office)
- Sections 10-11: Deployment requirements, risks
- Sections 12-15: Roadmap, paid services, anti-scope, glossary

## Feature Priority

- **P0 (MVP)**: Transparent multi-protocol proxy, read-through cache, cache consistency, remote change detection, cache space management, one-click deployment
- **P1**: WiFi setup AP + captive portal proxy, cache warm-up, CLI tools (`warpgate status/cache-list/warmup/bwlimit/...`), adaptive bandwidth throttling, connection resilience
- **P2**: WiFi AP sharing, web UI, NAS-side agent push, multi-NAS support, smart cache policies, Docker image, notifications

## Configuration

All behavior driven by environment variables — key groups:
- Connection: `NAS_HOST`, `NAS_USER`, `NAS_PASS`/`NAS_KEY_FILE`, `NAS_REMOTE_PATH`
- Cache: `CACHE_DIR`, `CACHE_MAX_SIZE`, `CACHE_MAX_AGE`, `CACHE_MIN_FREE`
- Read tuning: `READ_CHUNK_SIZE`, `READ_AHEAD`, `BUFFER_SIZE`
- Write-back: `VFS_WRITE_BACK` (default 5s), `TRANSFERS`
- Bandwidth: `BW_LIMIT_UP`, `BW_LIMIT_DOWN`, `BW_ADAPTIVE`
- Protocols: `ENABLE_SMB`, `ENABLE_NFS`, `ENABLE_WEBDAV`
- Directory cache: `DIR_CACHE_TIME`

## Language & Conventions

- PRD and product context are in **Simplified Chinese**
- Product name is **Warpgate** (English)
- NAS brand-agnostic: must work with Synology, QNAP, TrueNAS, DIY — SFTP only, no vendor APIs
- Deployment targets Linux only; clients are cross-platform