chore: add support for Claude

2 files changed, 104 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
index b6cfd39..3c35ead 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,4 @@
 .env.*
 /tmp
 /log
+.claude/
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..c220618
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,103 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+SparkleLab is a dual-purpose Go application for GitLab's Authorization team:
+1. **sparkled** - Web application for team members to send appreciation ("sparkles") to colleagues
+2. **authzd** - gRPC authorization service that integrates with Envoy Proxy for access control experiments
+
+The project serves as a real-world testbed for experimenting with RBAC, ABAC, and ReBAC authorization models while providing genuine value through team appreciation features.
+
+## Build and Development Commands
+
+### Setup and Dependencies
+```bash
+make setup          # Install all dependencies via mise, go mod, brew bundle, and pip
+```
+
+### Building
+```bash
+make build          # Build both sparkled and authzd binaries
+make bin/sparkled   # Build only the web application
+make bin/authzd     # Build only the authorization service
+```
+
+### Testing
+```bash
+make test           # Run all tests (unit + integration)
+make test-unit      # Run unit tests only
+make test-integration  # Run integration tests (requires Docker)
+make clean          # Clean test cache and binaries
+```
+
+### Running the Application
+```bash
+make run            # Run sparkled + envoy together (requires .env.local)
+make run-sparkled   # Run only the web application
+make run-authzd     # Run only the authorization service
+make run-envoy      # Run only Envoy proxy
+make run-image      # Run complete stack in Docker
+```
+
+### Code Quality
+```bash
+make lint           # Lint YAML files using yamlfmt
+make tidy           # Update dependencies and format YAML files
+```
+
+### Environment Setup
+Copy `.env` to `.env.local` and configure:
+- `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET` from GitLab OAuth app
+- `OIDC_ISSUER` (e.g., `http://gdk.test:3000`)
+
+## Architecture
+
+### Two-Service Architecture
+- **sparkled** (:8080) - Web application handling sparkle creation/viewing
+- **authzd** (:10003) - gRPC service implementing Envoy External Authorization API
+
+### Key Components
+
+**Web Application (sparkled)**:
+- Uses IoC container pattern for dependency injection
+- Controllers: `dashboard` and `sparkles` with RESTful endpoints
+- Middleware: User extraction, permission checking, logging
+- Domain models: `User`, `Sparkle` with validation logic
+- In-memory repository pattern for data persistence
+- Template-based HTML rendering
+
+**Authorization Service (authzd)**:
+- Implements `envoy.service.auth.v3.Authorization` gRPC interface
+- Provides authorization decisions for Envoy Proxy
+- Designed for experimenting with different access control models
+
+### Request Flow
+```
+User → Envoy Proxy (:1000) → GitLab OIDC → Envoy → sparkled (:8080)
+                           ↓
+                      authzd (:10003)
+```
+
+Envoy handles OIDC authentication and forwards requests to sparkled with user context. The authzd service can be consulted for authorization decisions.
+
+### Data Models
+- **Sparkle**: Appreciation messages with regex parsing for `@username reason` format
+- **User**: GitLab user representation with permissions
+- Uses ULID for unique identifiers
+
+### Testing Strategy
+- Unit tests for domain logic, controllers, and middleware
+- Integration tests using testcontainers for full-stack scenarios
+- Playwright for UI testing
+- Mock OIDC server for authentication testing
+
+## Development Notes
+
+- Go 1.24+ required
+- Uses mise for tool management
+- Follows standard Go project layout with `cmd/`, `pkg/`, `app/` structure
+- Dependencies vendored in `vendor/` directory
+- Static files served from `public/` directory
+- HTML templates in `app/views/`
\ No newline at end of file