-

CLAUDE.md

@@ -0,0 +1,198 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is an API Key Management Service (KMS) built with Go backend and React TypeScript frontend. The system manages API keys, user authentication, permissions, and provides both static tokens and user JWT tokens with hierarchical permission scopes.
+
+## Architecture
+
+The project follows clean architecture principles with clear separation:
+
+```
+cmd/server/          - Application entry point  
+internal/            - Go backend core logic
+├── domain/          - Domain models and business logic
+├── repository/      - Data access interfaces and PostgreSQL implementations  
+├── services/        - Business logic layer
+├── handlers/        - HTTP request handlers
+├── middleware/      - Authentication, logging, security middleware
+├── config/          - Configuration management
+└── database/        - Database connection and migrations
+kms-frontend/        - React TypeScript frontend with Ant Design
+migrations/          - PostgreSQL database migration files
+test/               - Integration and E2E tests
+```
+
+## Development Commands
+
+### Go Backend
+
+```bash
+# Run the server locally
+go run cmd/server/main.go
+
+# Build the binary
+go build -o api-key-service ./cmd/server
+
+# Run tests
+go test -v ./test/...
+
+# Run tests with coverage
+go test -v -coverprofile=coverage.out ./test/...
+go tool cover -html=coverage.out -o coverage.html
+
+# Run specific test suites
+go test -v ./test/ -run TestHealthEndpoints
+go test -v ./test/ -run TestApplicationCRUD
+go test -v ./test/ -run TestStaticTokenWorkflow
+go test -v ./test/ -run TestConcurrentRequests
+```
+
+### React Frontend
+
+```bash
+# Navigate to frontend directory
+cd kms-frontend
+
+# Install dependencies
+npm install
+
+# Start development server
+npm start
+
+# Build for production
+npm run build
+
+# Run tests
+npm test
+```
+
+### Docker & Development Environment
+
+```bash
+# Start all services (PostgreSQL, API, Nginx, Frontend)
+docker-compose up -d
+
+# Check service health
+curl http://localhost/health
+
+# View logs
+docker-compose logs -f
+
+# Stop services  
+docker-compose down
+```
+
+## Database Setup
+
+The project uses PostgreSQL with automatic migrations. For local development:
+
+```bash
+# Create development database
+psql -U postgres -c "CREATE DATABASE kms;"
+
+# Create test database  
+psql -U postgres -c "CREATE DATABASE kms_test;"
+```
+
+## Testing
+
+### End-to-End Testing
+
+```bash
+# Run comprehensive E2E tests with curl
+./test/e2e_test.sh
+
+# Test against different server
+BASE_URL=http://localhost:8080 USER_EMAIL=admin@example.com ./test/e2e_test.sh
+```
+
+### Test Environments
+
+The service provides different test user contexts on different ports:
+- Port 80: Regular user (`test@example.com`) 
+- Port 8081: Admin user (`admin@example.com`)
+- Port 8082: Limited user (`limited@example.com`)
+
+## Key Configuration
+
+Environment variables for configuration:
+
+```bash
+# Database
+DB_HOST=localhost
+DB_PORT=5432  
+DB_NAME=kms
+DB_USER=postgres
+DB_PASSWORD=postgres
+
+# Server
+SERVER_HOST=0.0.0.0
+SERVER_PORT=8080
+
+# Authentication  
+AUTH_PROVIDER=header
+AUTH_HEADER_USER_EMAIL=X-User-Email
+
+# Security
+RATE_LIMIT_ENABLED=true
+RATE_LIMIT_RPS=100
+RATE_LIMIT_BURST=200
+```
+
+## API Structure
+
+The API provides:
+- Health checks (`/health`, `/ready`)
+- Authentication (`/api/login`, `/api/verify`, `/api/renew`)
+- Application management (`/api/applications`)
+- Token management (`/api/applications/{id}/tokens`)
+- Permission hierarchies (repo.read, app.write, internal.admin, etc.)
+
+## Code Patterns
+
+### Backend Patterns
+- Repository pattern for data access with interfaces
+- Service layer for business logic with dependency injection
+- Middleware chain for authentication, logging, security
+- Structured error handling with custom error types
+- Comprehensive logging with zap structured logger
+
+### Frontend Patterns  
+- React functional components with TypeScript
+- Ant Design component library
+- Context API for authentication state
+- Axios for API communication
+- React Router for navigation
+
+## Permission System
+
+Hierarchical permission scopes:
+- `internal.*` - System operations
+- `app.*` - Application management  
+- `token.*` - Token operations
+- `repo.*` - Repository access (example domain)
+- `permission.*` - Permission management
+
+Parent permissions inherit child permissions (e.g., `repo` includes `repo.read` and `repo.write`).
+
+## Database Schema
+
+Key tables:
+- `applications` - Application definitions with HMAC keys
+- `static_tokens` - Static API tokens  
+- `available_permissions` - Permission catalog
+- `granted_permissions` - Token-permission relationships
+- `user_sessions` - User session tracking
+
+## Development Notes
+
+- The backend uses interfaces throughout for testability and dependency injection
+- Database migrations run automatically on startup
+- Rate limiting is configurable per endpoint  
+- All operations include audit logging with user attribution
+- Token security uses HMAC signing with rotation capabilities
+- Frontend uses protected routes with authentication context
+- E2E tests provide comprehensive API coverage with curl