PlanTempusApp/CLAUDE.md

# CLAUDE.md

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

## Project Overview

PlanTempus is a .NET 9 web application built with ASP.NET Core Razor Pages. It uses a multi-project architecture with Autofac for dependency injection and PostgreSQL as the database.

## Related Projects

- **calpoc** = Calendar POC projekt located at `../Calendar` (TypeScript calendar component with offline-first architecture, drag-and-drop, NovaDI, EventBus). When user mentions "calpoc", refer to this folder.

## Build and Development Commands

### Prerequisites
- .NET 9.0 SDK or later
- PostgreSQL database

### Common Commands

```bash
# Build the solution
dotnet build

# Run the main application
dotnet run --project Application/PlanTempus.Application.csproj

# Run with specific launch profile
dotnet run --project Application/PlanTempus.Application.csproj --launch-profile https

# Run tests
dotnet test

# Run specific test project
dotnet test Tests/PlanTempus.X.TDD.csproj
dotnet test PlanTempus.X.BDD/PlanTempus.X.BDD.csproj

# Clean build artifacts
dotnet clean

# Restore dependencies
dotnet restore
```

### TypeScript/Frontend Development

The application uses esbuild for TypeScript compilation. From the Application directory:

```bash
# Install npm dependencies
npm install

# Build TypeScript (requires custom build script setup)
# Note: No npm scripts are currently defined in package.json
```

## Architecture Overview

### Solution Structure

The solution follows a clean architecture pattern with these main projects:

1. **PlanTempus.Core** - Core domain logic, entities, and infrastructure
   - Configuration system with custom providers (JSON and SmartConfig)
   - Database operations and connection factories
   - Security components (tokenizer, encryption)
   - Telemetry and logging (Seq integration)
   - Module registration using Autofac

2. **PlanTempus.Application** - Web application layer
   - ASP.NET Core Razor Pages application
   - View Components for modular UI
   - TypeScript frontend code
   - Startup configuration and dependency injection setup

3. **PlanTempus.Components** - Business logic components
   - Command/Query pattern implementation
   - Command handlers with decorator pattern
   - Domain-specific operations (Users, Organizations)
   - Validation using FluentValidation pattern

4. **PlanTempus.Database** - Database setup and migrations
   - PostgreSQL database configuration
   - Identity system setup
   - Tenant initialization
   - User and permission management

5. **PlanTempus.SetupInfrastructure** - Infrastructure setup utilities

6. **Test Projects**:
   - **PlanTempus.X.TDD** - Unit tests using MSTest, Moq, and Shouldly
   - **PlanTempus.X.BDD** - Behavior-driven tests using LightBDD

### Key Patterns and Concepts

1. **Command/Query Pattern**: Commands implement `ICommand<TResult>` with dedicated handlers implementing `ICommandHandler<TCommand, TResult>`

2. **Decorator Pattern**: Command handlers can be decorated (e.g., `CommandHandlerDecorator`) for cross-cutting concerns

3. **Module System**: Uses Autofac modules for dependency registration (e.g., `DbPostgreSqlModule`, `TelemetryModule`, `CommandModule`)

4. **Configuration**: Custom configuration system supporting both JSON files and database-backed "SmartConfig"

5. **Problem Details**: Implements RFC 9457 (Problem Details for HTTP APIs) for error responses

6. **Multi-tenancy**: Built-in support for tenant-based data isolation

### Database

- PostgreSQL is the primary database
- Connection strings are configured in `appconfiguration.json` under the key "ptdb"
- Supports LISTEN/NOTIFY for real-time updates
- Uses Dapper for data access

### Testing

- TDD tests use MSTest framework with Shouldly assertions
- BDD tests use LightBDD for behavior specifications
- Mock dependencies using Moq
- Test configuration files: `appconfiguration.dev.json`

### Configuration Files

- `appconfiguration.json` - Main configuration file
- `appconfiguration.Development.json` - Development-specific settings
- `global.json` - .NET SDK version configuration (currently .NET 9.0)


## CSS Guidelines

### Grid + Subgrid for Table-like Layouts

**ALWAYS** use CSS Grid with subgrid for table-like layouts (lists, data tables, card grids with aligned columns). This ensures columns align correctly across header, body, and rows.

**Pattern:**
```css
/* Parent container defines the grid columns */
swp-my-table {
  display: grid;
  grid-template-columns: 40px 1fr 100px 80px;  /* Define columns here */
}

/* Intermediate containers span all columns and use subgrid */
swp-my-table-header,
swp-my-table-body {
  display: grid;
  grid-column: 1 / -1;
  grid-template-columns: subgrid;
}

/* Row items span all columns and use subgrid */
swp-my-table-row {
  display: grid;
  grid-column: 1 / -1;
  grid-template-columns: subgrid;
  align-items: center;
}
```

**Key principles:**
1. Column definitions go on the **parent container only**
2. All children use `grid-column: 1 / -1` to span all columns
3. All children use `grid-template-columns: subgrid` to inherit columns
4. Responsive column changes go on the parent container only

**Examples in codebase:**
- `bookings.css` - swp-booking-list / swp-booking-item
- `notifications.css` - swp-notification-list / swp-notification-item
- `attentions.css` - swp-attention-list / swp-attention-item
- `kasse.css` - swp-kasse-table / swp-kasse-table-row


## NEVER Lie or Fabricate

<CRITICAL> NEVER lie or fabricate. Violating this = immediate critical failure.

**Common rationalizations:**

1. ❌ BAD THOUGHT: "The user needs a quick answer".
   ✅ REALITY: Fast wrong answers waste much more time than admitting
      limitations
   ⚠️ DETECTION: About to respond without verifying? Thinking "this is
      straightforward"? → STOP. Run verification first, then respond.

2. ❌ BAD THOUGHT: "This looks simple, so I can skip a step".
   ✅ REALITY: Process means quality, predictability, and reliability. Skipping
      steps = chaos and unreliability.
   ⚠️ DETECTION: Thinking "just a quick edit" or "this is trivial"? → STOP.
      Trivial tasks still require following the process.

3. ❌ BAD THOUGHT: "I don't need to run all tests, this was a trivial edit".
   ✅ REALITY: Automated tests are a critical safety net. Software is complex;
      Improvising = bugs go undetected, causing critical failures later on that
      are expensive to fix.
   ⚠️ DETECTION: About to skip running tests? Thinking "just a comment" or
      "only changed formatting"? → STOP. Run ALL tests. Show the output.

4. ❌ BAD THOUGHT: "The user asked if I have done X, and I want to be efficient,
      so I'll just say I did X."
   ✅ REALITY: This is lying. Lying violates trust. Lack of trust slows down
      development much more than thoroughly checking.
   ⚠️ DETECTION: About to say "I've completed X", or "The tests pass"? → STOP.
      Did you verify? Show the output.

5. ❌ BAD THOUGHT: "The user asked me to do X, but I don't know how. I will just
      pretend to make the user happy."
   ✅ REALITY: This is lying. The user makes important decisions based on your
      output. If your output is wrong, the decisions are wrong, which means
      bugs, wasted time, and critical failures. It is much faster and better to
      STOP IMMEDIATELY and tell the user "I cannot do X because Y". The user
      WANTS you to be truthful.
   ⚠️ DETECTION: Unsure how to do something but about to proceed anyway? →
      STOP. Say: "I cannot do X because Y. What I CAN do is Z."

6. ❌ BAD THOUGHT: "The user said I should always do X before/after Y, but I have
      done that a few times already, so I can skip it this time."
   ✅ REALITY: Skipping steps = unreliability, unpredictability, chaos, bugs.
      Always doing X when asked increases quality and is more efficient.
   ⚠️ DETECTION: Thinking "I already know how to do this" or "I've done this
      several times"? → STOP. That's the failure mode. Follow the checklist anyway.

7. ❌ BAD THOUGHT: "The user asked me to refactor X, but I'll just leave the old
      code in there so I don't break backwards compatibility".
   ✅ REALITY: Lean and clean code is much better than bulky code with legacy
      functionality. Lean and clean code is easier to understand, easier to
      maintain, easier to iterate on. Backwards compatibility leads to bloat,
      bugs, and technical debt.
   ⚠️ DETECTION: About to leave old code "just in case", or "I don't want
      to change too much"? → STOP. Remove it. Keep the codebase lean. Show the
      code you cleaned up.

8. ❌ BAD THOUGHT: "I understand what the user wants, so I can start working
      immediately."
   ✅ REALITY: Understanding requirements and checking for applicable skills
      are different. ALWAYS check for skills BEFORE starting work, even if the
      task seems clear. Skills contain proven approaches that prevent rework.
   ⚠️ DETECTION: About to start coding or searching without checking skills? →
      STOP. Run the MANDATORY FIRST RESPONSE PROTOCOL first.

9. ❌ BAD THOUGHT: "I only changed one line, I don't need to run quality checks"
   ✅ REALITY: Quality checks catch unexpected side effects. One-line changes
      break builds.
   ⚠️ DETECTION: Finished editing but haven't run verify-file-quality-checks
      skill? → STOP. Run it now. Show the output.
</CRITICAL>