# CLAUDE.md

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

The development guidelines to consider are descibed in [docs/development_guidelines.md](./docs/development_guidelines.md)

## Project Overview

Blazor Server app (.NET 9.0) with Clean Architecture: Domain, Application, Infrastructure, Web layers. Uses ASP.NET Core Identity with dual DbContext pattern (AppDbContext for domain, AppIdentityDbContext for auth), MudBlazor UI, and Fluxor state management.

The name for the App is KOOGLE. Koogle is an app for club management. 

### Functional
- Club management
- Management of match days and games
- Registration of participants (members and guests)
- Automatic or rule-based cost allocation
- Evaluation per person/day/game
- User-related actions (CurrentUserService)

### Technical
- ASP.NET Core backend
- EF Core
- Multi-client capable (club as scope)
- Future web or mobile app realistic

### Target group
- primarily Bowling clubs (Kegelclub / Kegelvereine) - In German "Kegeln" is a bit different to bowling
- maybe in future also for darts, soccer betting pools, Leisure groups, Sport clubs, etc.

**Phase 1 MVP:** See [docs/IMPLEMENTATION_PLAN.md](./docs/IMPLEMENTATION_PLAN.md)
- 23 granular phases (A1-F3)
- Foundation → Clubs → Users → Persons → Days → Dashboard
- Track progress via checkboxes in plan
- ~75 files total

## Architecture

**Clean Architecture Layers:**
- `Koogle.Domain`: Entities, Enums, Interfaces (no dependencies)
- `Koogle.Application`: DTOs, Services, Mapping (depends on Domain, Infrastructure)
- `Koogle.Infrastructure`: DbContexts, Repositories, Identity, Security (depends on Domain)
- `Koogle.Web`: Blazor components, Controllers, Fluxor Store (depends on Application)

**Dual DbContext Pattern:**
- `AppDbContext`: Domain entities → `app` schema → `__EFMigrationsHistory_App`
- `AppIdentityDbContext`: ASP.NET Identity → `auth` schema → `__EFMigrationsHistory_Auth`

**Key Technologies:**
- Fluxor (Redux pattern): Store in `src/Koogle.Web/Store/`, Actions/Reducers/Effects pattern
- ASP.NET Identity: Custom `ApplicationUser`, `ApplicationRole`, `CustomClaimsPrincipalFactory`
- Authorization: Club-based roles (Viewer/Editor/Admin) via `ClubRoleRequirement`/`ClubRoleHandler`
- AutoMapper (Application layer), MudBlazor UI components

## Common Commands

### Build & Run
```bash
dotnet build
dotnet run --project src/Koogle.Web
```

### Database Migrations

**AppDbContext (domain data):**
```bash
# Create migration
dotnet ef migrations add [Name] --project src/Koogle.Infrastructure --startup-project src/Koogle.Web --context AppDbContext --output-dir Data/Migrations

# Apply migration
dotnet ef database update -p src/Koogle.Infrastructure -s src/Koogle.Web --context AppDbContext
```

**AppIdentityDbContext (auth data):**
```bash
# Create migration
dotnet ef migrations add [Name] --project src/Koogle.Infrastructure --startup-project src/Koogle.Web --context AppIdentityDbContext --output-dir Identity/Migrations

# Apply migration
dotnet ef database update -p src/Koogle.Infrastructure -s src/Koogle.Web --context AppIdentityDbContext
```

**Update EF Tools:**
```bash
dotnet tool update --global dotnet-ef --version 9.0.11
```

### Testing
```bash
dotnet test test/Koogle.Tests
```
The Test framework with xUnit, FluentAssertions, Moq etc. is described in [test\README.md](../KoogleApp/test/README.md)

## Development Notes

**DependencyInjection:**
- Each layer has `DependencyInjection.cs` registering services via extension methods
- Call order in `Program.cs`: AddInfrastructure → AddApplication → AddFluxor

**Authentication Flow:**
- Cookie-based auth (`/login` path)
- `CurrentUserService` (ICurrentUserService) provides user context
- `BootstrapSeeder` seeds super-admin, `IdentityRoleSeeder` seeds roles
- Blazor: `AuthStateInitializer.razor` syncs auth state, Fluxor `AuthState` for client state

**Authorization:**
- Custom club-based policies: `ClubViewer`, `ClubEditor`, `ClubAdmin`
- `ICurrentClubContext` provides club context for authorization decisions
- `ClubRoleHandler` evaluates requirements based on user's club membership

**Blazor Components:**
- Interactive server mode
- Layout: `MainLayout.razor`, `NavMenu.razor`
- Auth components: `AuthTest.razor`, `LogoutButton.razor`, `Account/Login.razor`

**Connection String:**
- Key: `AppDb` in `appsettings.json`
- Both contexts share same connection, different schemas/migration tables