From 1d0b785627b0d4bc7cad8637faecd208829241d7 Mon Sep 17 00:00:00 2001
From: rob thijssen <grenade@rob.tn>
Date: Thu, 12 Mar 2026 14:21:56 +0200
Subject: [PATCH] docs: add CLAUDE.md with project guidance

- Document project structure and workspace members
- Add development commands for building and testing
- Describe architecture and module organization
- Establish conventional commit syntax
- Document dependency management approach

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..3bbd065
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Structure
+
+This is a Rust workspace with four members:
+
+- **cichlid-api**: Axum-based HTTP server with a `/health` endpoint
+- **cichlid-cli**: CLI tool (currently under development)
+- **cichlid-data**: Data layer library (currently under development)
+- **cichlid-util**: Utility library providing app-specific machine ID generation
+
+## Development Commands
+
+```bash
+# Build the entire workspace
+cargo build
+
+# Run tests for all members
+cargo test
+
+# Run tests for a specific crate
+cargo test -p cichlid-util
+
+# Run tests for a specific test function
+cargo test test_machine_id
+
+# Run tests with output
+cargo test -- --nocapture
+```
+
+## Architecture
+
+The workspace follows a clean architecture pattern with separate crates for different concerns:
+
+- **API crate** (`bin/cichlid-api`): Uses Axum for HTTP routing. The main entry point is `main.rs` which sets up the router with handlers and state. Handlers are organized in `handlers/` modules, and application state is managed in `state.rs`.
+
+- **Util crate** (`lib/cichlid-util`): Provides shared utilities. Currently exports `APP_ID` constant for generating app-specific machine IDs using HMAC-SHA256 on `/etc/machine-id`.
+
+- **Data crate** (`lib/cichlid-data`): Reserved for data access layer and domain models.
+
+- **CLI crate** (`bin/cichlid-cli`): Reserved for command-line interface tools.
+
+## Commit Convention
+
+All commits must use conventional commit syntax with the format:
+
+```
+<type>[optional scope]: <description>
+```
+
+Common types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
+
+## Dependencies
+
+The workspace uses a shared dependency set in `Cargo.toml`. New dependencies should be added to the workspace dependencies section rather than individual crate manifests.
\ No newline at end of file