# CLAUDE.md

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

## What is buh

buh is a media automation engine that scrapes torrent indexers, indexes torrents and metadata, selects downloads via operator-defined ingestion/discard rules, queues downloads, processes downloaded files (renaming), and syncs them to LAN targets (e.g., Jellyfin media folders). Media types: shows, movies, music, books, audio-books.

## Build & Test Commands

```bash
cargo check --workspace          # fast type-check all crates
cargo build --workspace          # full build
cargo test --workspace           # run all tests
cargo test -p buh-entity         # test a single crate
cargo run -p buh-cli -- --help   # run the CLI
cargo run -p buh-cli -- daemon --config daemon.toml  # run daemon mode
cargo run -p buh-ws              # start the WebSocket server
```

The CLI binary is named `buh` (not `buh-cli`). When no subcommand is given, it defaults to `client` mode.

## Architecture

Cargo workspace with edition 2024, resolver 3. All shared dependencies are declared in the root `Cargo.toml` under `[workspace.dependencies]` and inherited by crates.

### Dependency graph (arrows = "depends on")

```
buh-entity          ← leaf crate, no internal deps, serde-only
    ↑
buh-data            ← Turso/libsql data access layer
    ↑
buh-util            ← domain logic (scraper, rules, processor, sync modules)
    ↑
buh-cli, buh-ws     ← binaries
```

### Crate responsibilities

- **buh-entity** — Pure data structs. No business logic, no database awareness. Only depends on `serde`. Every other crate imports this.
- **buh-data** — All database access goes through `Db` struct wrapping a libsql `Connection`. Uses `thiserror` for typed errors. Schema migrations live in `Db::migrate()`.
- **buh-util** — Domain logic organized as modules: `scraper` (indexer scraping), `rules` (ingestion/discard evaluation), `processor` (file renaming), `sync` (LAN file sync).
- **buh-cli** — Binary `buh` with two clap subcommands: `client` (default, interactive) and `daemon` (reads TOML config, runs routines). Config path defaults to `/etc/buh/daemon.toml`.
- **buh-ws** — Axum-based WebSocket server on port 9000, endpoint `/ws`.

### Error handling convention

Libraries (`buh-data`, `buh-util`, `buh-entity`) use `thiserror` for typed errors. Binaries (`buh-cli`, `buh-ws`) use `anyhow` for error erasure.

### Config format

Daemon configuration is TOML. The schema is defined in `buh-entity::config`. See `daemon.toml` at the repo root for an example.