# CLAUDE.md

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

## Project Overview

FTDL (Resource Download Website) is a Next.js-based internal network APK resource download tool. It provides a web interface for searching and downloading Android APK files organized by projects and versions.

## Development Commands

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test
npm run test:watch
npm run test:coverage
```

## Environment Variables

Required environment variables (create in `.env.local`):

- `AUTH_USERNAME` - Login username (default: `admin`)
- `AUTH_PASSWORD` - Login password (default: `changeme`)
- `RESOURCE_PATH` - Path to APK storage directory

## Project Structure

```
ftdl/
├── app/                 # Next.js App Router
│   ├── api/            # API routes
│   ├── download/       # Main download page
│   ├── login/          # Login page
│   └── layout.tsx      # Root layout
├── lib/                # Shared utilities and constants
│   ├── __tests__/      # Test files for lib modules
│   ├── constants.ts    # Environment variables and config
│   ├── fs-utils.ts     # File system operations with security
│   └── utils.ts        # Helper functions (formatting)
├── public/             # Static assets
├── middleware.ts       # Authentication middleware
└── *.config.*          # Configuration files (Jest, Next.js, etc.)
```

## Architecture

### Security Layer

All file system operations go through `lib/fs-utils.ts` which implements `validatePath()` to prevent path traversal attacks. The middleware (middleware.ts) protects all routes except `/login` using a simple cookie-based authentication.

### File System Abstraction

The application expects this resource directory structure:

```
RESOURCE_PATH/
├── PROJECT_NAME/
│   ├── VERSION_NAME/
│   │   └── apks/
│   │       └── *.apk
```

- Version names use underscores (e.g., `0_42`) but display with dots (`0.42`)
- APK filenames can contain commit IDs which are extracted via regex `([a-f0-9]{7,})` for filtering

### API Routes

Located in `app/api/`:
- `/api/projects` - List all project directories
- `/api/versions?project={name}` - List versions for a project
- `/api/apks?project={name}&version={name}&commitId={id}` - List APK files with optional commit filtering
- `/api/download?project={name}&version={name}&apk={name}` - Stream APK file for download
- `/api/login` - Handle authentication (sets cookie)

### Data Fetching

Client-side uses SWR for data fetching in the download flow:
1. User selects project → fetch projects
2. User selects version → fetch versions for that project
3. Optional commit filter → fetch filtered APKs
4. Download button triggers streaming download via API

### Key Files

- `lib/fs-utils.ts` - Core file system utilities with path validation
- `lib/constants.ts` - Environment variable defaults and cookie configuration
- `middleware.ts` - Route protection via Next.js middleware
- `app/download/page.tsx` - Main UI with search form and APK results