ftdl/CLAUDE.md

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

# 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