add claude.md

1 files changed, 111 insertions, 0 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..f42f64b
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,111 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Development Commands
+
+### Building
+```bash
+# Build all binaries
+make build
+
+# Build individual binaries
+make dserver    # Server daemon
+make dtail      # Main client
+make dcat       # Distributed cat
+make dgrep      # Distributed grep  
+make dmap       # MapReduce client
+make dtailhealth # Health check utility
+```
+
+### Testing
+```bash
+# Run all unit tests
+make test
+
+# Run integration tests (requires environment variable)
+DTAIL_INTEGRATION_TEST_RUN_MODE=yes go test -v ./integrationtests/
+
+# IMPORTANT: Always recompile binaries before running integration tests
+make clean build && DTAIL_INTEGRATION_TEST_RUN_MODE=yes go test -v ./integrationtests/
+
+# Clean test cache before running
+go clean -testcache
+```
+
+### Code Quality
+```bash
+# Run go vet on all packages
+make vet
+
+# Run linting
+make lint
+```
+
+### Installation
+```bash
+# Install all binaries to $GOPATH/bin
+make install
+```
+
+### Optional Build Tags
+- `DTAIL_USE_ACL=1` - Enable Linux ACL support  
+- `DTAIL_USE_PROPRIETARY=1` - Enable proprietary features
+
+## Architecture Overview
+
+DTail is a distributed log processing system with client-server architecture using SSH for secure communication.
+
+### Core Binaries
+- **dtail** - Main client for distributed log tailing and MapReduce
+- **dserver** - SSH-based server daemon (runs on port 2222)
+- **dcat/dgrep/dmap/dtailhealth** - Specialized distributed tools
+
+### Key Internal Components
+
+#### Client Architecture (`internal/clients/`)
+- All clients inherit from `baseClient` with SSH connection management
+- Client types: TailClient, CatClient, GrepClient, MaprClient, HealthClient
+- Connector pattern: ServerConnection (SSH) vs Serverless (local)
+- Handlers manage protocol communication
+
+#### Server Architecture (`internal/server/`) 
+- SSH server with multi-user support and resource management
+- Handler system routes requests to appropriate processors
+- Background services for scheduled jobs and continuous monitoring
+
+#### Protocol (`internal/protocol/`)
+- Binary message protocol with specific delimiters:
+  - `¬` for message separation
+  - `|` for field separation
+  - `≔` for key-value pairs in aggregations
+
+#### MapReduce System (`internal/mapr/`)
+- SQL-like query syntax: `SELECT...FROM...WHERE...GROUP BY`
+- Server-side local aggregation, client-side final aggregation
+- Pluggable log format parsers in `internal/mapr/logformat/`
+
+#### Configuration (`internal/config/`)
+- Hierarchical: Common, Server, Client configurations
+- Supports config files, environment variables, and CLI args
+
+#### Discovery (`internal/discovery/`)
+- Pluggable server discovery using reflection
+- Built-in: comma-separated, file-based, regex filtering
+
+## Development Patterns
+
+### Resource Management
+- Channel-based coordination and goroutine lifecycle management
+- Connection throttling using configurable limits per CPU core
+- Object recycling and buffer pools for high-throughput scenarios
+
+### Security Model
+- SSH-first architecture with encrypted communication
+- User-based access control with different privilege levels
+- Configurable host key verification policies
+
+### Error Handling
+- Structured logging with multiple levels and output targets
+- Graceful degradation when servers are unavailable
+- Context-aware operations using Go's context package