tech
8227f36cbe
- Move test files to lib/__tests__/ directory - Extract formatting utilities (formatVersion, formatFileSize, formatDateTime) from fs-utils.ts to new utils.ts module - Add Jest test configuration and test scripts - Update component imports to use new utils module - Add CLAUDE.md documentation for project structure Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
101 lines
3.2 KiB
Markdown
101 lines
3.2 KiB
Markdown
# 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
|