From b4c1daa84788c46efb15cc0c07cf0a3ca666f479 Mon Sep 17 00:00:00 2001 From: Natalia Portillo Date: Fri, 12 Jun 2026 20:33:14 +0100 Subject: [PATCH] feat: Add Claude Code setup documentation and skills for EF Core migration and DbContext analysis --- .claude/CLAUDE.md | 322 ++++++++++++++++++ .claude/settings.local.json | 7 + .claude/skills/dotnet-migration/SKILL.md | 146 ++++++++ .claude/skills/ef-dbcontext-analyzer/SKILL.md | 189 ++++++++++ 4 files changed, 664 insertions(+) create mode 100644 .claude/CLAUDE.md create mode 100644 .claude/settings.local.json create mode 100644 .claude/skills/dotnet-migration/SKILL.md create mode 100644 .claude/skills/ef-dbcontext-analyzer/SKILL.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 00000000..8f571e66 --- /dev/null +++ b/.claude/CLAUDE.md @@ -0,0 +1,322 @@ +# Claude Code Setup for Marechai + +This document describes Claude Code automation for the Marechai computing history catalog project. + +## Project Overview + +**Marechai** is a .NET 10.0 ASP.NET Core application for cataloging and displaying computing history artifacts. It consists of multiple interconnected projects: + +- **Marechai.Server**: ASP.NET Core Web API backend with OpenAPI documentation +- **Marechai.Database**: Entity Framework Core data access layer with MySQL/MariaDB +- **Marechai.App**: Uno Platform cross-platform client (Android, iOS, WASM, Desktop) +- **Marechai** (legacy): Original Blazor Server web application +- Supporting projects: Email, Translation, MobyGames, WinWorld integrations + +### Key Technologies + +- **.NET 10.0** (prerelease, see `global.json`) +- **Entity Framework Core 9.x** with **Pomelo MySQL** provider +- **Uno Platform SDK 6.5.36** for cross-platform UI +- **ASP.NET Core Identity** + JWT Bearer authentication +- **Blazorise** + MudBlazor for web UI components +- **SkiaSharp** for graphics/image processing + +### Database + +- **MySQL 8.0+** or **MariaDB 10.5+** +- Migrations stored in `Marechai.Database/Migrations/` +- Schema defined via DbContext in `Marechai.Database/Data/MarechaiDbContext.cs` +- Models in `Marechai.Database/Data/Models/` + +## Local Development Setup + +### Prerequisites + +```bash +# .NET 10.0 SDK (with prerelease enabled in global.json) +dotnet --version # Should show 10.0.x + +# Verify prerelease SDK is enabled +cat global.json + +# MySQL/MariaDB running locally +mysql --version + +# ImageMagick with HEIF/WebP/AVIF support (for image processing) +convert --version +``` + +### Initial Setup + +1. **Clone repository** + ```bash + git clone https://github.com/claunia/marechai.git + cd marechai + ``` + +2. **Configure database connection** + - Edit `Marechai/appsettings.json` - set `DefaultConnection` string + - Edit `Marechai.Server/appsettings.json` - set database connection + - Create database: `CREATE DATABASE marechai CHARACTER SET utf8mb4;` + +3. **Apply migrations** + ```bash + cd Marechai.Database + dotnet ef database update --project Marechai.Database + ``` + +4. **Build solution** + ```bash + dotnet build Marechai.slnx + ``` + +5. **Run web API** + ```bash + dotnet run --project Marechai.Server + # API available at https://localhost:7000 or http://localhost:5000 + ``` + +### Running the Cross-Platform App (Uno) + +```bash +# WebAssembly (browser) +dotnet run --project Marechai.App -c Debug -f net10.0-browser + +# Desktop (Windows/Linux/macOS) +dotnet run --project Marechai.App -c Debug -f net10.0-windows + +# Android (requires Android SDK) +dotnet run --project Marechai.App -c Debug -f net10.0-android +``` + +## Claude Code Skills + +Claude Code includes two specialized skills for managing the Marechai data model: + +### `/dotnet-migration-generator` + +**Purpose**: Generate, validate, and document EF Core migrations + +**When to use**: +- Adding new tables or columns to the database schema +- Modifying entity relationships +- Creating data migrations (seeding, transformations) +- Validating migration correctness before commit + +**Examples**: +``` +/dotnet-migration-generator Add a new UserPreference table with Name and Value properties +/dotnet-migration-generator Validate the last 3 migrations for correctness +/dotnet-migration-generator Document the migration for the new ComputerFamily feature +``` + +**Key Points**: +- Operates on `Marechai.Database` project +- Uses `dotnet ef migrations add` under the hood +- Validates migrations compile and don't conflict +- Follows semantic naming conventions +- Includes both Up() and Down() implementations + +### `/ef-dbcontext-analyzer` + +**Purpose**: Analyze and document Entity Framework Core structure + +**When to use**: +- Understanding entity relationships +- Documenting the data model for new team members +- Identifying missing navigation properties or indexes +- Checking cascade delete configurations +- Validating DbContext consistency + +**Examples**: +``` +/ef-dbcontext-analyzer What is the relationship between Computer and Manufacturer? +/ef-dbcontext-analyzer Document the complete Software domain with all related entities +/ef-dbcontext-analyzer Check for orphaned entities or circular relationships +/ef-dbcontext-analyzer Show cascade delete configurations for all relationships +``` + +**Key Points**: +- Analyzes `Marechai.Database/Data/MarechaiDbContext.cs` +- Maps all DbSet properties and their configurations +- Documents navigation properties and foreign keys +- Identifies configuration issues and patterns + +## Coding Conventions + +### C# Style + +- Follow `.editorconfig` rules (UTF-8, 2-space indent, 120 char line length) +- Use C# 12+ features as appropriate +- Use PascalCase for public members, camelCase for private + +### Naming + +- **ViewModels**: `{Feature}ViewModel` (e.g., `ComputersListViewModel`) +- **Services**: `{Feature}Service` (e.g., `ComputersService`) +- **Pages/Views**: `{Feature}Page` (e.g., `ComputersListPage`) +- **Controllers**: `{Feature}Controller` (e.g., `ComputersController`) +- **Migrations**: `{YYYYMMDD}_{SemanticName}` (e.g., `20250612_AddUserPreferencesTable`) + +### Architecture + +- **Marechai.App**: MVVM with ViewModels in `Presentation/ViewModels/`, Views in `Presentation/Views/` +- **Marechai.Server**: Controller-based Web API with services in `Services/` +- **Marechai.Database**: Repository pattern with operations in `Operations/` +- **Dependency Injection**: Register in `App.xaml.cs` (Uno) or `Program.cs` (ASP.NET) + +## Git Workflow + +### Commits + +**Claude must never create a commit on its own.** Only commit when the user +explicitly asks for a commit in that turn — never as a follow-up step after +finishing a task, fix, or feature, even if it seems like the natural next +action. + +**All commits must be cryptographically signed** (see `CONTRIBUTING.md`). + +```bash +# Configure signing (one-time) +git config user.signingkey + +# Sign commits by default +git config commit.gpgsign true + +# Commit with signing (automatic if configured) +git commit -m "feat: Add user preferences feature" +``` + +### Branch Naming + +- Feature: `feature/description` +- Bug fix: `fix/issue-number-description` +- Refactor: `refactor/description` +- Docs: `docs/description` + +**Example**: `feature/add-user-preferences` + +### Pull Requests + +1. Keep changes focused and easy to review +2. Update documentation when behavior or setup changes +3. Validate locally before opening PR: + ```bash + dotnet build Marechai.slnx + dotnet test + ``` +4. Write clear PR description explaining what and why + +## Common Tasks + +### Add a Database Field + +```bash +# 1. Edit the entity model +# File: Marechai.Database/Data/Models/ComputerModel.cs +# Add property: public string? NewField { get; set; } + +# 2. Generate migration +/dotnet-migration-generator Add NewField to Computer entity + +# 3. Review generated migration in Marechai.Database/Migrations/ + +# 4. Apply locally +dotnet ef database update --project Marechai.Database +``` + +### Create a New API Endpoint + +1. Add method to `Marechai.Server/Controllers/{Feature}Controller.cs` +2. Include OpenAPI documentation (XML comments) +3. Use dependency injection for services +4. Return appropriate HTTP status codes + +### Add a New Uno Page + +1. Create ViewModel: `Marechai.App/Presentation/ViewModels/{Feature}ViewModel.cs` +2. Create View: `Marechai.App/Presentation/Views/{Feature}Page.xaml` +3. Register in `App.xaml.cs`: + ```csharp + .AddView<{Feature}Page, {Feature}ViewModel>() + ``` +4. Add route to `RouteMap` in `App.xaml.cs` + +### Understand Data Relationships + +``` +/ef-dbcontext-analyzer Show the relationship between {Entity1} and {Entity2} +``` + +This will show navigation properties, foreign keys, cardinality, and delete behavior. + +## Important Files + +- `Marechai.slnx` - Modern solution file (use this, not `.sln`) +- `Directory.Build.props` - Shared MSBuild properties +- `Directory.Packages.props` - Central NuGet package version management +- `global.json` - SDK version and prerelease settings +- `.editorconfig` - Code style rules for all languages +- `AGENTS.md` - Detailed architecture and patterns reference +- `CONTRIBUTING.md` - Contribution guidelines and signing instructions + +## MCP Servers + +Two MCP servers are recommended for this project: + +1. **GitHub MCP** (`claude mcp add github`) + - View and manage PRs, issues, and actions + - Review code directly from Claude + +2. **Microsoft Docs MCP** (built-in) + - Look up .NET, ASP.NET Core, EF Core documentation + - Search Microsoft Learn for API references + +## Troubleshooting + +### Migrations Won't Apply + +```bash +# Check for pending migrations +dotnet ef migrations list --project Marechai.Database + +# Verify database connection +dotnet ef dbcontext info --project Marechai.Database + +# Revert last migration (if needed) +dotnet ef migrations remove --project Marechai.Database +``` + +### Build Fails + +```bash +# Clean build +dotnet clean Marechai.slnx +dotnet build Marechai.slnx + +# Check SDK version +dotnet --version + +# Verify dependencies +dotnet restore +``` + +### Database Connection Issues + +- Check `appsettings.json` connection string format +- Verify MySQL/MariaDB is running: `mysql -u root -p` +- Test connection: `dotnet ef dbcontext info --project Marechai.Database` + +## Resources + +- **AGENTS.md** - Detailed architecture patterns and guidelines +- **CONTRIBUTING.md** - Contribution workflow and commit signing +- **GitHub**: https://github.com/claunia/marechai +- **Microsoft Learn**: https://learn.microsoft.com/en-us/dotnet/ +- **Entity Framework Core**: https://learn.microsoft.com/en-us/ef/core/ +- **Uno Platform**: https://platform.uno/ + +--- + +**Last updated**: June 2026 +**For Claude Code assistance**: `/help` or https://github.com/anthropics/claude-code/issues diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 00000000..61a52922 --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,7 @@ +{ + "permissions": { + "allow": [ + "Bash(dotnet build *)" + ] + } +} diff --git a/.claude/skills/dotnet-migration/SKILL.md b/.claude/skills/dotnet-migration/SKILL.md new file mode 100644 index 00000000..a20aec32 --- /dev/null +++ b/.claude/skills/dotnet-migration/SKILL.md @@ -0,0 +1,146 @@ +--- +name: dotnet-migration-generator +description: Generate, validate, and document EF Core database migrations with proper naming and structure +disable-model-invocation: false +user-invocable: true +--- + +# EF Core Migration Generator + +Generate and manage Entity Framework Core migrations for the Marechai.Database project with proper naming conventions and validation. + +## Usage + +Invoke with a description of the schema change: + +``` +/dotnet-migration-generator Add support for storing user preferences with new UserPreference table +``` + +Or validate an existing migration: + +``` +/dotnet-migration-generator Validate the latest migration in Marechai.Database +``` + +## What This Skill Does + +1. **Generate Migrations**: Creates new EF Core migrations with semantic names based on the change description +2. **Validate Structure**: Ensures migrations follow project conventions (naming, methods, Up/Down implementations) +3. **Document Changes**: Generates migration summary showing entities, properties, and relationships affected +4. **Verify Compilation**: Checks that migrations compile and don't conflict with existing ones + +## How to Use + +### Generate a New Migration + +Tell the skill what database schema change you want: + +> I need to add a nullable `Biography` field to the `People` table and a new `PersonSource` enum type. + +The skill will: +1. Update relevant DbContext models in `Marechai.Database/Data/` +2. Run `dotnet ef migrations add ` with a semantic name +3. Review the generated migration file for correctness +4. Compile and validate with `dotnet build Marechai.Database.csproj` +5. Output a summary of what changed + +### Validate Migrations + +Ask to review migrations before commit: + +> Validate the last 3 migrations to ensure they're safe + +The skill checks: +- Migration naming follows `_` or similar convention +- `Up()` and `Down()` methods are balanced +- No breaking changes without data migration strategies +- SQL syntax is correct for MySQL/MariaDB + +### Document Migration Impact + +> Document the migration for the new ComputerFamily feature + +The skill generates a summary showing: +- Entities modified/created +- Properties added/changed/removed +- Relationship changes +- Default values and constraints + +## Project Context + +**Database Project**: `Marechai.Database` +**DbContext**: `Marechai.Database/Data/MarechaiDbContext.cs` +**Models Location**: `Marechai.Database/Data/Models/` +**Migrations Location**: `Marechai.Database/Migrations/` +**Database**: MySQL/MariaDB via Pomelo.EntityFrameworkCore.MySql + +**Key Files**: +- `.editorconfig` - C# formatting rules (migrations must comply) +- `Directory.Packages.props` - Central version management (EF Core 9.0.11, Pomelo 9.0.0) + +## Migration Naming Conventions + +Migrations in this project follow a semantic naming pattern: + +- `_` (e.g., `20250612_AddUserPreferencesTable`) +- Names should reflect the primary change (Add, Remove, Refactor, Rename) +- Avoid overly long names; focus on the main entity/change + +## Best Practices + +1. **Small, Focused Migrations**: Each migration should address one logical change +2. **Data Migrations**: If adding NOT NULL columns to existing tables, include data seeding in the migration +3. **Reversibility**: Both `Up()` and `Down()` must be implemented correctly +4. **Testing**: Run migrations locally before committing +5. **Documentation**: Complex migrations should include comments in the Up/Down methods + +## Pre-Migration Checklist + +Before generating a migration: + +- [ ] Verify the DbContext model changes are complete +- [ ] Check for any data type compatibility with MySQL/MariaDB +- [ ] Consider impact on existing data (constraints, nullability, foreign keys) +- [ ] Ensure the migration doesn't break existing relationships + +## Commands This Skill Uses + +```bash +# View pending migrations +dotnet ef migrations list --project Marechai.Database + +# Add a new migration +dotnet ef migrations add --project Marechai.Database + +# Update database with migrations +dotnet ef database update --project Marechai.Database + +# Remove last migration (if not applied) +dotnet ef migrations remove --project Marechai.Database + +# Build and validate +dotnet build Marechai.Database.csproj +``` + +## Examples + +**Adding a new table:** +``` +/dotnet-migration-generator Add a new SoftwareLicense table with Name, Abbreviation, and URL properties +``` + +**Modifying an existing entity:** +``` +/dotnet-migration-generator Add ReleaseDate property to the Software entity as nullable DateTime +``` + +**Refactoring relationships:** +``` +/dotnet-migration-generator Rename PersonCompany.Company navigation to Companies and update foreign key references +``` + +**Data migration:** +``` +/dotnet-migration-generator Populate the new Status enum field for existing records with default value 'Active' +``` diff --git a/.claude/skills/ef-dbcontext-analyzer/SKILL.md b/.claude/skills/ef-dbcontext-analyzer/SKILL.md new file mode 100644 index 00000000..0770bc43 --- /dev/null +++ b/.claude/skills/ef-dbcontext-analyzer/SKILL.md @@ -0,0 +1,189 @@ +--- +name: ef-dbcontext-analyzer +description: Analyze and document Entity Framework Core DbContext structure, models, and relationships +disable-model-invocation: false +user-invocable: true +--- + +# EF Core DbContext Analyzer + +Analyze and document the Entity Framework Core structure, entities, relationships, and configurations in the Marechai project. + +## Usage + +Invoke to understand or document your data model: + +``` +/ef-dbcontext-analyzer Analyze the relationship between Computer and Manufacturer entities +``` + +Or generate comprehensive documentation: + +``` +/ef-dbcontext-analyzer Document the complete data model for the Software and License domain +``` + +## What This Skill Does + +1. **Analyze Entities**: Maps out all DbSet properties, their models, and relationships +2. **Document Relationships**: Shows one-to-many, many-to-many, and one-to-one relationships +3. **Identify Constraints**: Documents primary keys, foreign keys, unique constraints, and indexes +4. **Generate ER Diagrams**: Creates a text-based entity relationship overview +5. **Validate Configuration**: Checks fluent API configurations and shadow properties +6. **Find Cross-Cutting Concerns**: Identifies shared patterns (soft delete, timestamps, audit fields) + +## How to Use + +### Understand an Entity + +Ask about a specific entity to understand its structure and relationships: + +> Analyze the Computer entity and show all its relationships to other entities + +The skill will show: +- Properties (type, nullable, constraints) +- Navigation properties and relationships +- Foreign key configurations +- Any index or unique constraints +- How it's used by other entities + +### Explore a Domain Area + +Understand a logical domain within the data model: + +> Map out the entire Software domain including Software, Genre, Publisher, and License relationships + +The skill generates: +- Entity definitions and properties +- How they relate to each other +- Data flow between entities +- Any shared configurations or patterns + +### Generate Documentation + +Create reference documentation for new developers: + +> Generate ER diagram documentation for the Media and Storage entities + +Output includes: +- ASCII or Mermaid diagram +- Property definitions +- Relationship descriptions +- Cardinality and constraints + +### Identify Configuration Issues + +Ask about potential issues in the DbContext: + +> Check for any orphaned or circular relationships in the data model + +The skill will flag: +- Missing foreign key constraints +- Potentially problematic cascade deletes +- Entities not included in DbSet +- Inconsistent naming or pattern violations + +## Project Context + +**DbContext Location**: `Marechai.Database/Data/MarechaiDbContext.cs` +**Models Location**: `Marechai.Database/Data/Models/` +**Configuration Location**: `Marechai.Database/Data/Configuration/` +**Database**: MySQL/MariaDB via Pomelo.EntityFrameworkCore.MySql (EF Core 9.0.11) + +**Key Patterns in This Project**: +- Uses `IEntityTypeConfiguration` for entity configurations +- Supports soft delete tracking (look for `IsDeleted` or similar fields) +- May use shadow properties for timestamps or audit fields +- MySQL-specific configurations for JSON columns (`Json.Microsoft`) + +## Common Queries + +### "What entities does Person relate to?" +The skill will trace all navigation properties from the Person entity and show cardinality. + +### "Are there any unused DbSets?" +Checks all DbSet properties against references in migrations and services. + +### "What's the relationship between X and Y?" +Identifies the specific foreign key, navigation properties, and delete behavior. + +### "Show me the full model for a domain area" +Generates comprehensive documentation including all related entities and their interactions. + +### "What are the cascade delete settings?" +Lists all relationships and their `OnDelete` behavior (Cascade, SetNull, Restrict, etc.). + +## DbContext Analysis Output Format + +When analyzing, the skill typically provides: + +``` +Entity: Computer +├─ Properties: +│ ├─ Id: int (PK) +│ ├─ Name: string +│ └─ ReleaseDate: DateTime? +├─ Navigation Properties: +│ ├─ Manufacturer: Manufacturer (FK: ManufacturerId) +│ ├─ Computers: List (inverse) +├─ Configurations: +│ └─ HasIndex(c => c.Name) +└─ Related Entities: [Manufacturer, ComputerVariant, Software] +``` + +## Examples + +**Analyze a relationship:** +``` +/ef-dbcontext-analyzer What is the relationship between Software and SoftwareGenre? Show the navigation properties and foreign key +``` + +**Document a domain:** +``` +/ef-dbcontext-analyzer Create ER documentation for the Person, Company, and Contact domain +``` + +**Find configuration issues:** +``` +/ef-dbcontext-analyzer Check for any orphaned entities (DbSet properties that aren't referenced elsewhere) +``` + +**Understand cascade behavior:** +``` +/ef-dbcontext-analyzer Show all delete cascade configurations - which entities will be deleted if their parent is removed +``` + +**Model evolution:** +``` +/ef-dbcontext-analyzer Compare the Software entity between two migration points and show what changed +``` + +## Common Findings + +This skill often identifies: + +- **Missing Navigation Properties**: Relationships defined via foreign keys but not exposed as navigation properties +- **Asymmetric Relationships**: One side has a navigation property but the other doesn't +- **Naming Inconsistencies**: Foreign key names that don't match naming conventions +- **Unused Configurations**: Fluent API configurations that duplicate Annotations +- **Performance Issues**: Potentially missing indexes on frequently queried fields + +## Integration with Other Skills + +Works well with: +- **dotnet-migration-generator**: Understanding the current model before proposing schema changes +- **API Documentation**: DbContext structure informs API DTO design +- **Testing**: Entity relationships inform test data setup + +## Commands Used + +```bash +# List all entities in DbContext +dotnet ef dbcontext info --project Marechai.Database + +# Generate script from current model +dotnet ef dbcontext scaffold-async --project Marechai.Database + +# Check pending changes +dotnet build Marechai.Database.csproj +```