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

# 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

# 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