booklog: Instructions file for Claude Code

Claude Code Guidelines for Booklog

Project Overview

Booklog is a self-hosted book tracking platform built in Rust: HTTP server (Axum + Askama + Datastar), REST API, CLI client, SQLite database.

Build & Test Commands

prek run -av                      # All lints, tests, formatters
cargo build                       # Build
cargo test                        # Tests
cargo clippy --allow-dirty --fix  # Lint + auto-fix
nix fmt                           # Format
sqlx migrate add <name>           # New migration → migrations/NNNN_<name>.sql

Workflow Requirements

Before finishing any task, always:

1. Run prek run -av
2. Consider if the test coverage needs updating
3. Update README.md if the change adds/removes/renames CLI commands, env vars, or user-facing features
4. Update scripts/bootstrap-db.sh if the change affects CLI commands, flags, or entity fields used by it
5. Provide a draft commit message using Conventional Commits format

Architecture

Clean Architecture / DDD with four layers:

src/
├── domain/              # Pure business logic, no external deps
│   ├── errors.rs        # RepositoryError enum
│   ├── ids.rs           # Typed ID wrappers (AuthorId, BookId, ReadingId, etc.)
│   ├── listing.rs       # Pagination & sorting (SortKey, ListRequest, Page, PageSize)
│   ├── repositories.rs  # Repository traits
│   ├── countries.rs     # Country name → ISO code, flag emoji
│   ├── formatting.rs    # format_relative_time(), format_pages(), format_rating()
│   ├── books/           # authors, books (with BookAuthor), readings
│   ├── auth/            # users, sessions, tokens, passkeys, registration_tokens
│   └── analytics/       # timeline, stats, country_stats, ai_usage
├── infrastructure/      # DB, HTTP clients, third-party APIs
│   ├── repositories/    # SQL impls of repository traits (books/, auth/, analytics/)
│   ├── client/          # HTTP client for CLI
│   ├── ai.rs            # OpenRouter LLM integration
│   ├── backup.rs        # Database backup/restore
│   └── database.rs      # Database pool + SQLite pragmas
├── application/         # HTTP server, routes, middleware, services
│   ├── routes/          # Axum handlers (api/ for REST, app/ for web UI)
│   ├── services/        # Entity services (create + timeline event)
│   └── errors.rs        # HTTP error mapping
└── presentation/        # User interfaces
    ├── cli/             # CLI commands
    └── web/             # View models for templates