# CLAUDE.md

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

## Project Overview

**ym-dl** — A Go service for monitoring and downloading tracks/albums from Yandex Music for configured artists.

- **Language**: Go (strict typing, idiomatic patterns)
- **Runtime**: Docker / Docker Compose
- **API**: Yandex Music (OpenAPI spec at `docs/yandex-music.yaml`)
- **Config**: YAML file listing artist IDs to monitor

## Architecture

```
ym-dl/
├── cmd/ym-dl/           # Main entry point
├── internal/
│   ├── config/          # Configuration loading (artist IDs, API credentials)
│   ├── yandex/          # Yandex Music API client (generated from OpenAPI)
│   ├── storage/         # Local file storage for downloaded tracks/albums
│   ├── monitor/         # Periodic check logic for new releases
│   └── downloader/      # Download orchestration
├── docker-compose.yml   # Service definition
├── Dockerfile           # Multi-stage build
└── config.yaml.example  # Sample configuration
```

## Development Commands

```bash
# Build
go build -o bin/ym-dl ./cmd/ym-dl

# Run locally
go run ./cmd/ym-dl --config config.yaml

# Run with Docker Compose
docker compose up --build

# Run tests
go test ./...

# Run single test
go test -v -run TestName ./internal/...

# Lint
golangci-lint run

# Generate API client from OpenAPI
oapi-codegen -generate types,client -package yandex docs/yandex-music.yaml > internal/yandex/client.gen.go
```

## Configuration

`config.yaml` structure:
```yaml
yandex:
  token: "oauth_token"        # Or use username/password for token exchange
  username: "login"
  password: "password"

artists:
  - id: 12345                 # Artist ID from Yandex Music
  - id: 67890

storage:
  path: "/data/music"         # Local path for downloads
  organize: true              # Organize into Artist/Album/Track structure

monitor:
  interval: "24h"             # Check interval (duration string)
```

## Key Implementation Notes

- **Authentication**: Support both OAuth token and username/password (token exchange via `/token` endpoint)
- **Rate limiting**: Respect Yandex API limits; implement exponential backoff
- **Idempotency**: Track downloaded files by Yandex track/album ID to avoid re-downloads
- **Progress**: Structured logging (JSON) for Docker environments

## Docker

Multi-stage build: builder (Go 1.23+) → runtime (distroless or alpine). Mount config at `/config.yaml`, storage at `/data`.

## Testing

- Unit tests for config, storage, monitor logic
- Integration tests against mocked Yandex API (use `net/http/httptest`)
- No real API calls in CI