diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | CLAUDE.md | 103 |
2 files changed, 104 insertions, 0 deletions
@@ -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 |