# 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/`