From c27ace9c8558ab5b9b933e41146932e6160521ae Mon Sep 17 00:00:00 2001
From: Max Resnick <max@ofmax.li>
Date: Fri, 4 Jul 2025 23:55:42 -0700
Subject: chore: add CLAUDE.md

---
 CLAUDE.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..4336c20
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,97 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is `go-git-server`, an experimental Git HTTP server in Go that provides authentication and authorization for Git repositories. It wraps the built-in `git-http-backend` CGI process to maintain compatibility while adding security features.
+
+## Key Architecture
+
+- **Main Entry Point**: `cmd/main.go` - HTTP server with middleware stack
+- **Core Components**:
+  - `internal/git/handler.go` - Git HTTP backend CGI wrapper
+  - `internal/authz/` - Authentication/authorization middleware using Casbin
+  - `internal/admin/` - Administrative services and configuration management
+- **Configuration**: Uses Casbin for RBAC with auth model (`auth_model.ini`) and policy files
+- **Authentication**: Token-based system with bcrypt hashing stored in CSV format
+- **Authorization**: Role-based access control with roles like admin, maintainers, bots
+
+## Common Commands
+
+### Development
+```bash
+# Run tests and linting
+just test
+
+# Build the application
+just build <version>
+
+# Run server locally with debug mode
+just debug-run
+
+# Run specific test with debugger
+just debug-test <package> <function>
+
+# Run server with sample data
+just run [repo_path]
+```
+
+### Testing
+```bash
+# Run all tests with coverage
+just test
+
+# Coverage is automatically generated in temp directories
+```
+
+### Building and Deployment
+```bash
+# Create new version and build
+just release <part>  # where part is: patch, minor, major, or latest
+
+# Build Docker image
+just docker-build
+
+# Local Kubernetes deployment
+just local-deploy
+
+# Clean build artifacts
+just clean
+```
+
+### Token Management
+```bash
+# Generate new authentication token
+go run cmd/tokentool/main.go -generate -name <username>
+
+# List existing tokens
+go run cmd/tokentool/main.go -list
+
+# Generate token directly from main binary
+./main -g
+```
+
+## Development Notes
+
+- **Go Version**: Requires Go 1.24+
+- **Dependencies**: Uses Casbin for authorization, go-git for Git operations
+- **Testing**: Uses standard Go testing with coverage reporting
+- **Linting**: Uses golangci-lint
+- **Build System**: Uses `just` (justfile) for task automation
+- **Container**: Designed for Kubernetes deployment with minimal dependencies
+
+## Configuration Files
+
+- `gitserver.yaml` - Server configuration and repository definitions
+- `auth_model.ini` - Casbin authentication model
+- `policy.csv` - Casbin authorization policies
+- `tokens.csv` - Authentication tokens (format: access_id,friendly_name,hash)
+
+## Code Conventions
+
+From `CONVENTIONS.md`:
+- Prefer idiomatic Go code
+- Minimize dependencies
+- Expert-level Git and Go programming expected
+- Building a proxy server for `git-http-backend`
\ No newline at end of file
-- 
cgit v1.2.3