deepdrft/DeepDrftModels/CLAUDE.md

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:

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

Generic pagination configuration with LINQ expression support:

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:

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

Container for paginated data with metadata:

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:

public required string MediaPath { get; set; }  // Compile-time requirement

Nullable Reference Types

Explicit nullability throughout:

public string? Album { get; set; }      // Optional nullable
public required string Artist { get; set; }  // Required non-null

Generic Type Conversion

PagedResult supports type transformation:

public static PagedResult<T> From<TOther>(PagedResult<TOther> other, IEnumerable<T> items)

Expression-Based Sorting

Type-safe LINQ expressions for dynamic sorting:

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:

set => _pageSize = value > _maxPageSize ? _maxPageSize : value;

1-Based Pagination

Page numbers start at 1 (not 0) following common UI patterns:

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.