CLAUDE.md files

2025-09-04 19:57:05 -04:00
parent 97ad4e3ac7
commit 5e02d004e3
9 changed files with 1219 additions and 1 deletions
@@ -0,0 +1,163 @@
+# CLAUDE.md - DeepDrftModels
+
+This file provides guidance to Claude Code (claude.ai/code) when working with the DeepDrftModels project.
+
+## Project Overview
+
+DeepDrftModels is a **shared models library** that defines common data structures, entities, DTOs, and model classes used across the entire DeepDrft solution. It serves as the data contract layer between all projects.
+
+## Architecture
+
+### Technology Stack
+- **.NET 9.0 Class Library**: Shared library targeting .NET 9
+- **Entity Framework Compatible**: Entities work with EF Core
+- **JSON Serializable**: Models support JSON serialization for APIs
+
+### Project Structure
+```
+DeepDrftModels/
+├── Entities/           # Database entities
+│   └── TrackEntity.cs  # Core track data model
+├── DTOs/              # Data Transfer Objects
+│   └── TrackDto.cs    # Track DTO for API transfers
+├── Models/            # Shared model classes
+│   ├── PagingParameters.cs  # Pagination configuration
+│   └── PagedResult.cs       # Paginated result wrapper
+└── DeepDrftModels.csproj   # Project file
+```
+
+## Core Models
+
+### TrackEntity
+Primary database entity for track metadata:
+```csharp
+public class TrackEntity
+{
+    public long Id { get; set; }                    // Primary key
+    public required string MediaPath { get; set; }  // FileDatabase vault reference
+    public required string TrackName { get; set; }  // Track title
+    public required string Artist { get; set; }     // Artist name
+    public string? Album { get; set; }               // Optional album
+    public string? Genre { get; set; }               // Optional genre
+    public DateOnly? ReleaseDate { get; set; }       // Optional release date
+    public string? ImagePath { get; set; }           // Optional cover image path
+}
+```
+
+### TrackDto
+Data transfer object matching TrackEntity structure for API operations:
+- Mirrors all TrackEntity properties
+- Used for JSON serialization/deserialization
+- Client-server data exchange
+
+## Pagination System
+
+### PagingParameters<T>
+Generic pagination configuration with LINQ expression support:
+```csharp
+public class PagingParameters<T> : PagingParameters
+{
+    public Expression<Func<T, object>>? OrderBy { get; set; }  // Sorting expression
+    public bool IsDescending { get; set; } = false;           // Sort direction
+    public int Skip => (Page - 1) * PageSize;                 // Calculated skip count
+}
+```
+
+### PagingParameters
+Base pagination class with size constraints:
+```csharp
+public class PagingParameters
+{
+    public int Page { get; set; } = 1;           // Current page (1-based)
+    public int PageSize { get; set; } = 20;      // Items per page (max 100)
+}
+```
+
+### PagedResult<T>
+Container for paginated data with metadata:
+```csharp
+public class PagedResult<T>
+{
+    public IEnumerable<T> Items { get; set; }    // Page items
+    public int TotalCount { get; set; }          // Total items available
+    public int Page { get; set; }                // Current page
+    public int PageSize { get; set; }            // Items per page
+    
+    // Calculated properties
+    public int TotalPages { get; }               // Total pages available
+    public bool HasNextPage { get; }             // Can navigate forward
+    public bool HasPreviousPage { get; }         // Can navigate backward
+}
+```
+
+## Key Patterns
+
+### Required Properties
+Uses C# required modifier for essential properties:
+```csharp
+public required string MediaPath { get; set; }  // Compile-time requirement
+```
+
+### Nullable Reference Types
+Explicit nullability throughout:
+```csharp
+public string? Album { get; set; }      // Optional nullable
+public required string Artist { get; set; }  // Required non-null
+```
+
+### Generic Type Conversion
+PagedResult supports type transformation:
+```csharp
+public static PagedResult<T> From<TOther>(PagedResult<TOther> other, IEnumerable<T> items)
+```
+
+### Expression-Based Sorting
+Type-safe LINQ expressions for dynamic sorting:
+```csharp
+parameters.OrderBy = entity => entity.TrackName;  // Compile-time checked
+```
+
+## Integration Points
+
+### Entity Framework
+- `TrackEntity` configured for EF Core in `DeepDrftWeb.Data.Configurations`
+- Long Id as primary key for SQLite compatibility
+- DateOnly support for release dates
+
+### API Serialization
+- All models JSON-serializable for web API usage
+- DTO pattern separates data transfer from domain models
+
+### Cross-Project Usage
+Referenced by:
+- **DeepDrftWeb**: Entity Framework, services, repositories
+- **DeepDrftWeb.Client**: API client communication
+- **DeepDrftContent**: API DTOs (potential future usage)
+- **DeepDrftTests**: Test data and assertions
+
+## External Dependencies
+
+### NetBlocks Library
+Some projects reference `NetBlocks.Models` for:
+- `ResultContainer<T>`: Consistent result handling pattern
+- `ApiResult<T>`: API response wrapper
+- `Result`: Simple operation result
+
+## Development Notes
+
+### Page Size Limits
+Maximum page size enforced at 100 items to prevent performance issues:
+```csharp
+set => _pageSize = value > _maxPageSize ? _maxPageSize : value;
+```
+
+### 1-Based Pagination
+Page numbers start at 1 (not 0) following common UI patterns:
+```csharp
+public int Skip => (Page - 1) * PageSize;  // Convert to 0-based for queries
+```
+
+### Immutable Design
+Models favor immutability where possible, using init-only properties and required fields.
+
+When working with this project, maintain consistency in data models across the solution and preserve the established patterns for pagination, nullability, and type safety.