# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

AuthentiKate is a lightweight SSO/OIDC solution built with Laravel and Livewire, designed as a simpler alternative to Authentik for homelabbers. It provides OpenID Connect authentication services with JWT token generation and user management.

## Development Commands

### Laravel/PHP Commands
- `composer run dev` - Start development environment (combines server, queue, logs, and vite)
- `composer run test` - Run test suite with config clearing
- `php artisan serve` - Start Laravel development server
- `php artisan queue:listen --tries=1` - Start queue worker
- `php artisan pail --timeout=0` - Start log monitoring
- `php artisan migrate` - Run database migrations
- `php artisan key:generate` - Generate application key

### Frontend Commands
- `npm run dev` - Start Vite development server
- `npm run build` - Build assets for production

### Docker Commands
- `make build` - Build Docker image (runs npm build first)
- `make run` - Run container on port 8889
- `make rebuild` - Force rebuild without cache
- `make setup` - Install Laravel Octane with FrankenPHP

### Testing
- Uses Pest PHP testing framework
- Test files located in `tests/Feature/` and `tests/Unit/`
- Run with `composer run test` or `php artisan test`

## Architecture

### Core Components

**OIDC Implementation** (`app/Http/Controllers/OIDCController.php`):
- Authorization endpoint with PKCE support
- JWT token generation using RSA256 signing
- User info endpoint for profile data
- JWKS and OpenID configuration endpoints
- Uses Laravel Cache for authorization codes

**User Management**:
- `User` model with avatar support and authentication tokens
- `Application` model for OAuth clients
- `AuthenticationToken` model for access token tracking
- `Invitation` system for user onboarding

**Frontend**:
- Livewire components for reactive UI
- Flux UI components for consistent design
- Tailwind CSS for styling
- Vite for asset building

### Key Files
- `routes/web.php` - Main application routes including OIDC endpoints
- `app/Livewire/ConsentScreen.php` - OAuth consent flow
- `database/migrations/` - Database schema definitions
- `storage/oauth/` - RSA key pair for JWT signing

### Security Features
- PKCE (Proof Key for Code Exchange) support
- JWT token validation with RSA signatures
- Client secret verification
- Redirect URI validation
- CSRF protection (disabled for token endpoint)

## Database
- Uses SQLite by default
- Migrations handle users, applications, authentication tokens, and invitations
- Seeders available for development data

## Configuration
- Standard Laravel `.env` configuration
- OAuth keys stored in `storage/oauth/`
- Uses Laravel's built-in authentication system
- Email verification and password reset supported
- Uses the free version of FluxUI. A livewire component library.

## Code Guidance
- Stop initializing collections using collect(). This is not compatible with Database\Eloquent\Collection. It is also not necessary to do this since the components are only visible to the admin