claunia/marechai
1
0
Fork 0
mirror of https://github.com/claunia/marechai.git synced 2026-07-08 17:57:08 +00:00
Code Issues 15 Packages Projects Releases Wiki Activity

feat: Add Claude Code setup documentation and skills for EF Core migration and DbContext analysis

Browse Source
This commit is contained in:
Natalia Portillo
2026-06-12 20:33:14 +01:00
parent 338bedc8d4
commit b4c1daa847
4 changed files with 664 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

322
.claude/CLAUDE.md Normal file
View File

@@ -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 <your-key-id>
# 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

7
.claude/settings.local.json Normal file
View File

@@ -0,0 +1,7 @@
{
"permissions": {
"allow": [
"Bash(dotnet build *)"
]
}
}

146
.claude/skills/dotnet-migration/SKILL.md Normal file
View File

@@ -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 <MigrationName>` 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 `<YYYYMMDD>_<SemanticName>` 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:
- `<YYYYMMDD>_<PascalCaseDescription>` (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 <MigrationName> --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'
```

189
.claude/skills/ef-dbcontext-analyzer/SKILL.md Normal file
View File

@@ -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<T>` 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<Computer> (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
```