# CLAUDE.md

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

## Project Overview

ASP.NET Core application based on ASP.NET Boilerplate framework with multi-tenancy support, targeting .NET 9.0. Uses PostgreSQL database and JWT Bearer authentication. The project follows a layered architecture pattern with distinct separation of concerns.

## Build & Run Commands

### Build
```bash
cd aspnet-core
dotnet build ASPBaseOIDC.sln
```

### Run the application
```bash
cd aspnet-core/src/ASPBaseOIDC.Web.Host
dotnet run
```
The API will be available at https://localhost:44311/
Swagger UI accessible at https://localhost:44311/swagger

### Run database migrations
```bash
cd aspnet-core/src/ASPBaseOIDC.Migrator
dotnet run
# Or with quiet mode (for CI/CD):
dotnet run -- -q
```

### Run tests
```bash
cd aspnet-core/test/ASPBaseOIDC.Tests
dotnet test
```

## Architecture

### Layer Structure
The solution follows ABP's multi-layer architecture:

- **ASPBaseOIDC.Core** - Domain layer containing entities, domain services, authorization logic, and business rules. Houses the core `Tenant`, `Role`, `User` entities and defines permissions in `PermissionNames`.

- **ASPBaseOIDC.Application** - Application service layer implementing use cases. App Services inherit from `ASPBaseOIDCAppServiceBase` and expose DTOs. Key services: `UserAppService`, `RoleAppService`, `TenantAppService`, `SessionAppService`.

- **ASPBaseOIDC.EntityFrameworkCore** - Data access layer with EF Core. Contains `ASPBaseOIDCDbContext` which inherits from `AbpZeroDbContext`. Database migrations live here. Important: DateTime values are automatically converted to UTC via ValueConverter in OnModelCreating.

- **ASPBaseOIDC.Web.Core** - Web infrastructure shared between hosting models. Contains authentication configuration (`AuthConfigurer`), identity setup (`IdentityRegistrar`), and base controllers.

- **ASPBaseOIDC.Web.Host** - ASP.NET Core Web API hosting. Entry point with `Startup.cs` configuring CORS, Swagger, SignalR, and ABP framework. Controllers expose Application Services as REST endpoints.

- **ASPBaseOIDC.Migrator** - Standalone console application for running database migrations in production environments. Supports quiet mode (`-q`) for automated deployments.

### ABP Framework Integration
The project uses ABP (ASP.NET Boilerplate) modules system:
- Each layer has a Module class (e.g., `ASPBaseOIDCCoreModule`, `ASPBaseOIDCApplicationModule`)
- Modules declare dependencies via `[DependsOn]` attribute
- Dependency injection configured through module initialization (PreInitialize, Initialize, PostInitialize)
- Multi-tenancy controlled by `ASPBaseOIDCConsts.MultiTenancyEnabled`

### Authentication
- JWT Bearer tokens (configured in appsettings.json under Authentication:JwtBearer)
- Security key: `ASPBaseOIDC_C629CD4D2F524E3AA105B46C2D2FC3BC`
- Issuer/Audience: `ASPBaseOIDC`
- Swagger UI includes Bearer token authentication scheme

### Database
- PostgreSQL database (connection string in appsettings.json)
- EF Core migrations in `ASPBaseOIDC.EntityFrameworkCore/Migrations`
- DateTime handling: All DateTime values automatically converted to UTC when saving/reading
- To add new migration: `dotnet ef migrations add <MigrationName> --project src/ASPBaseOIDC.EntityFrameworkCore --startup-project src/ASPBaseOIDC.Web.Host`

## Configuration

- **appsettings.json** in Web.Host: Main configuration for connection strings, app URLs, CORS origins, JWT settings, Kestrel endpoints
- **appsettings.Staging.json**: Environment-specific overrides
- **User Secrets**: Both Core and Web.Host projects use UserSecretsId `JJSolutions-ASPBaseOIDC-56C2EF2F-ABD6-4EFC-AAF2-2E81C34E8FB1`
- **log4net.config**: Logging configuration (log4net.Production.config for production)

## Key Conventions

- Application Services follow naming: `{Entity}AppService` implementing `I{Entity}AppService`
- DTOs organized in Dto folders alongside services
- Authorization: Permissions defined in `PermissionNames.cs`, granted in `ASPBaseOIDCAuthorizationProvider`
- Localization: XML files in Core/Localization/SourceFiles
- ABP auto-validates antiforgery tokens via `AbpAutoValidateAntiforgeryTokenAttribute`

## Development Workflow

**IMPORTANT**: Whenever you make changes to the codebase, you MUST update `changelog.md` with:
- Date and description of changes made
- Files modified/created/deleted
- Important notes about the changes
- Any breaking changes or migration steps required

This ensures context is preserved across sessions and other developers can understand what has been modified.