SWPCore/CLAUDE.md

# CLAUDE.md

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

## Build and Development Commands

```bash
# Build the solution
dotnet build

# Build in release mode
dotnet build -c Release

# Clean build artifacts
dotnet clean

# Restore NuGet packages
dotnet restore

# Run a specific project (from project directory)
dotnet run

# Run all tests
dotnet test

# Run tests with detailed output
dotnet test --logger "console;verbosity=normal"

# Run only unit tests (excluding integration tests)
dotnet test --filter "TestCategory!=Integration"

# Run tests with coverage
dotnet test --settings Tests/.runsettings --collect:"XPlat Code Coverage"
```

## Architecture Overview

This is a .NET 9.0 solution with a modular architecture using Autofac for dependency injection. The codebase follows these key patterns:

### Core Project Structure (SWP.Core)
- **CommandQueries**: CQRS pattern implementation with ICommand interface
- **Configurations**: Multi-provider configuration system supporting JSON files and database-backed smart configuration
- **Database**: PostgreSQL data access layer using Insight.Database ORM with connection factory pattern
- **ModuleRegistry**: Autofac modules for dependency registration (Security, Telemetry, Seq Logging, Database)
- **Telemetry**: Application Insights integration with custom enrichers and Seq telemetry channel
- **SeqLogging**: Structured logging implementation with Seq API integration

### Database Project Structure (PlanTempus.Database)
- Database setup and configuration management
- Identity system setup (DDL)
- User management with DCL scripts for different user types (Application, Organization, DbAdmin)
- Tenant initialization
- Navigation and roles/permissions systems

### Key Architectural Patterns
1. **Repository Pattern**: Used for configuration management (IConfigurationRepository)
2. **Factory Pattern**: Database connection management (IDbConnectionFactory)
3. **Module Pattern**: Autofac modules organize dependencies by feature
4. **CQRS Elements**: Command pattern with correlation and transaction IDs
5. **Smart Configuration**: Database-backed configuration provider that integrates with .NET configuration system

### Technology Stack
- .NET 9.0
- PostgreSQL with Npgsql and Insight.Database ORM
- Autofac for dependency injection
- FluentValidation for validation
- Seq API for structured logging
- Application Insights for telemetry
- Sodium.Core for encryption
- Newtonsoft.Json for JSON processing

### Security Features
- SecureTokenizer service for token generation
- Multi-key encryption with MasterKey management
- Secure connection string handling

## Testing Structure

The solution includes a comprehensive test project `SWP.Core.X.TDD` using:
- **MSTest** as the test framework
- **Moq** for mocking dependencies  
- **Shouldly** for fluent assertions
- **Coverlet** for code coverage

### Test Categories
- **Unit Tests**: Fast, isolated tests for individual components
- **Integration Tests**: Tests requiring database or external dependencies (marked with `[TestCategory("Integration")]`)

### Running Specific Tests
```bash
# Run tests for a specific class
dotnet test --filter "ClassName=SecureTokenizerTests"

# Run tests by category
dotnet test --filter "TestCategory=Integration"

# Run tests by name pattern
dotnet test --filter "Name~Token"
```

### Test Helpers
- `TestDataBuilder`: Factory methods for creating test data
- `TestFixtureBase`: Base class for test setup and teardown

### Known Test Issues
- Some tests require external dependencies (Seq logging server, PostgreSQL)
- Integration tests are marked with `[Ignore]` when external dependencies are not available
- Current SecureTokenizer implementation has null handling issues that need fixing

## Naming Conventions

The project follows a comprehensive naming convention documented in `NAMING_CONVENTION.md`. Key points:

### Code Style
- **Namespaces**: PascalCase with `SWP.Core` prefix (not `PlanTempus.Core`)
- **Classes**: PascalCase with appropriate suffixes (`Factory`, `Service`, `Exception`, etc.)
- **Interfaces**: PascalCase with `I` prefix
- **Methods**: PascalCase, async methods end with `Async`
- **Properties**: PascalCase
- **Private fields**: camelCase with `_` prefix
- **Parameters**: camelCase

### File Organization
- One main class per file
- File names match class names (PascalCase)
- Folder structure mirrors namespace hierarchy

### Test Naming
- Test classes: `[ClassName]Tests`
- Test methods: `[MethodName]_Should[Behavior]_[Condition]`
- Test projects: `[ProjectName].X.TDD`

### Configuration
- `.editorconfig` enforces formatting rules
- Hierarchical configuration keys with PascalCase sections
- Database uses snake_case, C# uses PascalCase with proper mapping