CLAUDE.md#

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

Project Overview#

This is atproto-identity, a comprehensive Rust library for AT Protocol identity management. The project provides full functionality for DID resolution, handle resolution, and identity document management across multiple DID methods.

Common Commands#

Build: cargo build
Run tests: cargo test
Run specific test: cargo test test_name
Check code: cargo check
Format code: cargo fmt
Lint: cargo clippy
Run CLI tool: cargo run --bin atproto-identity-resolve -- <handle_or_did>
Run CLI with DID document: cargo run --bin atproto-identity-resolve -- --did-document <handle_or_did>

Architecture#

A comprehensive Rust library with:

Modular architecture with 7 core modules (resolve, plc, web, model, validation, config, errors)
Complete CLI tool for identity resolution (atproto-identity-resolve)
Rust edition 2021 with modern async/await patterns
Comprehensive error handling with structured error types
Multiple external dependencies for HTTP, DNS, JSON, and cryptographic operations
Full test coverage with unit tests for all modules

Error Handling#

All error strings must use this format:

error-atproto-identity-<domain>-<number> <message>: <details>

Example errors:

error-atproto-identity-resolve-1 Multiple DIDs resolved for method
error-atproto-identity-plc-1 HTTP request failed: https://google.com/ Not Found
error-did-web-1 Invalid DID format: missing 'did:web:' prefix

Errors should be represented as enums using the thiserror library when possible using src/errors.rs as a reference and example.

Avoid creating new errors with the anyhow!(...) macro.

When a function call would return anyhow::Error, use the following pattern to log the error in addition to any code specific handling that must occur

If let Err(err) = result {
    tracing::error!(error = ?error, "Helpful contextual log line.");
}

Logging#

Use tracing for structured logging.

Async calls should be instrumented using the .instrument() that references the use tracing::Instrument; trait.

Module Structure#

src/lib.rs: Main library exports
src/resolve.rs: Core resolution logic for handles and DIDs, DNS/HTTP resolution
src/plc.rs: PLC directory client for did:plc resolution
src/web.rs: Web DID client for did:web resolution and URL conversion
src/model.rs: Data structures for DID documents and AT Protocol entities
src/validation.rs: Input validation for handles and DIDs
src/config.rs: Configuration management and environment variable handling
src/errors.rs: Structured error types following project conventions
src/bin/atproto-identity-resolve.rs: CLI tool for identity resolution