buhfin/CLAUDE.md

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

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.