1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
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/`
|
