DeutschLernen/AGENTS.md

DeutschLernen Solution Development Instructions

This file contains project-specific instructions, rules, and workflows for Mistral Vibe CLI when working on the DeutschLernen solution, which includes:

• GermanApp (Backend: ASP.NET Core Web API, .NET 9.0)
• german-app-frontend (Frontend: React 19, TypeScript, Vite)

This solution follows Clean Architecture principles.

---

Solution Architecture: Clean Architecture

The solution is structured according to Uncle Bob's Clean Architecture principles with the following layers:

┌─────────────────────────────────────────────────────────────┐
│                    PRESENTATION LAYER                          │
│  ┌─────────────────────┐  ┌───────────────────────────────┐  │
│  │   german-app-frontend │  │        GermanApp Controllers  │  │
│  │   (React + TypeScript)│  │     (ASP.NET Core Minimal APIs)│  │
│  └─────────────────────┘  └───────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│                    APPLICATION LAYER                           │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  Use Cases, Application Services, DTOs, Command/Query    │  │
│  │  - GermanApp/Application/                                      │  │
│  │  - MediatR pattern for CQRS (recommended)                   │  │
│  │  - Business logic orchestration                              │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│                      DOMAIN LAYER                               │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  Core Business Logic, Entities, Value Objects, Domain     │  │
│  │  Events, Domain Services                                   │  │
│  │  - GermanApp/Domain/                                            │  │
│  │  - Pure C# (no framework dependencies)                       │  │
│  │  - Contains enterprise-wide business rules                    │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│                   INFRASTRUCTURE LAYER                         │
│  ┌─────────────────────┐  ┌───────────────────────────────┐  │
│  │  Data Access          │  │  External Services             │  │
│  │  - Repositories       │  │  - Email, SMS, Payments        │  │
│  │  - Entity Framework   │  │  - File Storage                │  │
│  │  - DbContext          │  │  - Caching                     │  │
│  └─────────────────────┘  └───────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

The Dependency Rule

Inner layers MUST NOT depend on outer layers. Dependencies flow INWARD:

• Presentation → Application → Domain
• Infrastructure → Domain (via interfaces defined in Domain/Application)
• Infrastructure → Application (implementations of interfaces)

Key Principles

1. Single Responsibility: Each class has one reason to change
2. Open/Closed: Open for extension, closed for modification
3. Liskov Substitution: Subtypes must be substitutable
4. Interface Segregation: Clients shouldn't depend on unused interfaces
5. Dependency Inversion: Depend on abstractions, not concretions

---

Project Structure

Backend: GermanApp (ASP.NET Core)

GermanApp/
├── Domain/                      # Domain Layer (Pure C#)
│   ├── Entities/               # Business entities
│   ├── ValueObjects/           # Immutable value objects
│   ├── Enums/                  # Domain enums
│   ├── Exceptions/             # Domain-specific exceptions
│   ├── Interfaces/             # Domain interfaces (repositories, services)
│   └── DomainEvents/           # Domain events
│
├── Application/                # Application Layer
│   ├── UseCases/               # Use case handlers (CQRS pattern)
│   │   ├── Commands/           # Command handlers
│   │   └── Queries/            # Query handlers
│   ├── DTOs/                   # Data Transfer Objects
│   ├── Interfaces/             # Application service interfaces
│   └── Services/               # Application services
│
├── Infrastructure/             # Infrastructure Layer
│   ├── Data/                   # Data persistence
│   │   ├── Repositories/       # Repository implementations
│   │   └── DbContext/          # Entity Framework context
│   ├── Services/               # External service implementations
│   └── Configurations/         # Dependency injection configs
│
├── Presentation/               # Presentation Layer
│   ├── Controllers/            # API Controllers
│   ├── Endpoints/              # Minimal API endpoints
│   └── Models/                 # API request/response models
│
├── Shared/                     # Shared utilities
│   ├── Constants/              # Application constants
│   ├── Extensions/             # Extension methods
│   └── Helpers/                # Helper classes
│
├── Program.cs                  # Application entry point
├── appsettings.json            # Configuration
└── Tests/                      # Test projects
    ├── Unit/
    │   ├── Domain/
    │   ├── Application/
    │   └── Infrastructure/
    └── Integration/

Frontend: german-app-frontend (React + TypeScript)

german-app-frontend/
├── public/                     # Static files
├── src/
│   ├── assets/                # Static assets (images, fonts)
│   ├── components/            # React components
│   │   ├── ui/                # Reusable UI components
│   │   ├── layout/            # Layout components
│   │   └── features/          # Feature-specific components
│   │
│   ├── hooks/                  # Custom React hooks
│   ├── lib/                    # Utility functions, constants
│   │   └── api/               # API client, service calls
│   │
│   ├── stores/                 # State management
│   ├── types/                  # TypeScript type definitions
│   │   └── api/               # API types (mirror backend DTOs)
│   │
│   ├── pages/                  # Page components
│   ├── routes/                 # Routing configuration
│   │
│   ├── styles/                 # Global styles, themes
│   │
│   ├── App.tsx                 # Main application component
│   └── main.tsx                # Application entry point
│
├── package.json
└── tsconfig.json

---

Code Style & Conventions

Backend (C#)

General C# Standards

• Use PascalCase for all public types, methods, properties, and constants
• Use camelCase for local variables, method parameters, and private fields
• Use _camelCase with underscore prefix for private fields
• Use UPPER_SNAKE_CASE for constants

Formatting

• 4 spaces for indentation (no tabs)
• Opening braces on the same line (K&R style)
• One blank line between methods
• Line length: Keep under 120 characters when practical

Naming Conventions

• Interfaces: Prefix with I (e.g., IUserRepository, IEmailService)
• Async methods: Suffix with Async
• Records: Use PascalCase for properties
• Boolean properties: Prefix with Is, Has, Can, or Should
• Domain entities: Use business terminology (e.g., Lesson, VocabularyWord)
• Value objects: Use descriptive names (e.g., EmailAddress, GermanWord)

Clean Architecture Specific

• Domain Layer: Pure C# with NO framework dependencies
  • No using Microsoft.AspNetCore...
  • No using System.Web...
  • Only primitive types or other domain types
• Interfaces in Domain/Application: Define interfaces where they are USED
• Implementations in Infrastructure: Implement interfaces defined in inner layers
• DTOs: Use Record types for immutable DTOs
• Entities: Use classes with private setters for mutable entities

.NET Specific

• Use nullable reference types (enabled in project)
• Prefer records over classes for DTOs and immutable data
• Use Minimal APIs style for simple endpoints
• Use explicit typing for public APIs, var for local variables
• Use File-scoped namespaces

Frontend (TypeScript/React)

TypeScript

• Use PascalCase for types, interfaces, classes
• Use camelCase for variables, functions, properties
• Use SCREAMING_SNAKE_CASE for constants
• Use ISomething prefix for interfaces (optional but consistent)

React

• Components: PascalCase (e.g., UserCard, LessonList)
• Hooks: Use use prefix (e.g., useUser, useLessons)
• Props: Use TypeScript interfaces for prop types
• Events: Use on prefix for event handlers (e.g., onClick, onSubmit)

File Naming

• Components: ComponentName.tsx
• Hooks: useHookName.ts
• Utilities: utilityName.ts
• Types: types.ts or TypeName.ts
• Constants: constants.ts

API Client

• Use axios or fetch with a centralized API client
• Mirror backend DTO types in src/types/api/
• Use consistent naming: getUser, createLesson, updateVocabularyWord

---

Testing Requirements

Backend (MsTest)

• Framework: MsTest (required)
• Coverage: All business logic must have unit tests
• Integration tests: For API endpoints and database interactions

Test Structure

Tests/
├── Unit/
│   ├── Domain/
│   │   └── Entities/
│   │       └── UserTests.cs
│   ├── Application/
│   │   └── UseCases/
│   │       └── CreateUserCommandHandlerTests.cs
│   └── Infrastructure/
│       └── Repositories/
│           └── UserRepositoryTests.cs
│
└── Integration/
    ├── Api/
    │   └── WeatherForecastEndpointTests.cs
    └── Database/
        └── UserRepositoryIntegrationTests.cs

Test Naming (Backend)

• Test classes: [ClassUnderTest]Tests
• Test methods: MethodName_Scenario_ExpectedBehavior

Frontend (Vitest)

• Framework: Vitest (recommended for Vite projects)
• Component tests: Test user interactions and rendering
• Unit tests: Test utility functions and hooks

Test Naming (Frontend)

• Test files: *.test.tsx or *.test.ts
• Test blocks: describe('ComponentName', () => {...})
• Test cases: it('should do something when condition', () => {...})

Test Quality (Both)

• Follow Arrange-Act-Assert pattern
• Each test should test ONE thing
• Use meaningful test data, not magic numbers/strings
• Mock external dependencies (API calls, database, etc.)
• Keep tests fast and isolated

---

Git Workflow

Branching Strategy: GitHub Flow

1. main - Production-ready code (protected)
2. feature/* - Feature branches created from main
3. bugfix/* - Bug fix branches created from main
4. refactor/* - Refactoring branches

Branch Naming

• feature/[short-description] - e.g., feature/add-user-authentication
• bugfix/[short-description] - e.g., bugfix/lesson-load-error
• refactor/[short-description] - e.g., refactor/domain-entities
• docs/[short-description] - For documentation changes
• Use kebab-case (lowercase with hyphens)

Commit Conventions: Conventional Commits

type(scope): description

Types: feat, fix, docs, style, refactor, test, chore, perf

Scope: Should indicate the layer or project:

• feat(backend): or feat(domain): or feat(api):
• feat(frontend): or feat(ui):

Examples:

feat(backend/domain): add User entity with validation
feat(frontend/ui): create LessonCard component
fix(backend/api): handle null values in weather endpoint
refactor(backend/application): extract user creation use case

Pull Requests

• All changes must go through a Pull Request
• PR title should follow Conventional Commits format
• PR description should include:
  • What changed
  • Why it changed
  • Screenshots/GIFs for UI changes
  • Which Clean Architecture layer(s) were affected
• Minimum 1 approval required
• All CI checks must pass before merging

---

Development Workflow

Backend Commands

# Build
dotnet build

# Run
dotnet run --project GermanApp

# Tests
dotnet test
dotnet test /p:CollectCoverage=true

# Add package
dotnet add GermanApp package PackageName

Frontend Commands

# Install
npm install

# Dev server
npm run dev

# Build
npm run build

# Lint
npm run lint

# Tests
npm run test

Before Pushing

1. Run all tests (backend and frontend)
2. Check for lint/warnings
3. Review changes: git diff main
4. Ensure no Clean Architecture violations
5. Squash commits if needed

---

Clean Architecture Implementation Guidelines

Domain Layer (Pure C#)

• NO framework dependencies
• Contains: Entities, Value Objects, Domain Events, Domain Services, Interfaces
• Entities should have identity (Id) and business behavior
• Value Objects should be immutable

Application Layer

• Contains: Use Cases, DTOs, Application Services, Interfaces
• Orchestrates domain objects to fulfill use cases
• Defines interfaces for infrastructure (repositories, services)
• Uses MediatR pattern for CQRS (recommended)

Infrastructure Layer

• Contains: Repository implementations, DbContext, External services
• Implements interfaces defined in Domain/Application layers
• Entity Framework Core for data access
• External service adapters (email, file storage, etc.)

Presentation Layer

• Backend: Minimal APIs, Controllers, API Models
• Frontend: React components, hooks, state management
• Thin layer that handles presentation concerns only
• Delegates business logic to Application layer

Dependency Injection Setup

// In Program.cs

// Domain layer - no registration needed (pure logic)

// Application layer
builder.Services.AddApplicationServices();

// Infrastructure layer
builder.Services.AddInfrastructureServices(configuration);

// Presentation layer
builder.Services.AddPresentationServices();

---

Cross-Cutting Concerns

API Contracts

• Backend: Define API models in Presentation/Models
• Frontend: Mirror these types in src/types/api/
• Keep API contracts stable and versioned
• Use DTOs for all API communication (never domain entities directly)

Error Handling

• Domain: Throw domain-specific exceptions
• Application: Handle domain exceptions, map to application errors
• Presentation: Map to appropriate HTTP status codes
• Frontend: Display user-friendly error messages

Validation

• Domain: Entity/Value Object validation (business rules)
• Application: Use case validation (cross-entity rules)
• Presentation: Request model validation (FluentValidation)
• Frontend: Client-side validation (Zod, Yup, or similar)

---

Feature Implementation & Tracking

For complex features, use the Feature Tracking System in docs/features/:

Feature Documentation Structure

docs/features/
├── README.md              # Feature tracking overview & workflow
├── template.md           # Template for new feature implementation plans
└── [feature-name].md      # Individual feature files with:
     # - Status (Planned/In Progress/Code Review/Completed)
     # - Priority & Complexity
     # - Requirements & Technical Design
     # - Implementation Plan & Tasks
     # - Dependencies & Notes

Workflow

1. Create: Copy template.md → [feature-name].md, fill in details
2. Plan: Set status to ⏳ Planned, add to README.md table
3. Develop: Update status to 🚀 In Progress, check off tasks
4. Review: Set status to 🔄 Code Review, link PR in feature file
5. Complete: Set status to ✅ Completed, document lessons learned

Status Icons

• ⏳ Planned - Feature defined, not started
• 🚀 In Progress - Actively being developed
• 🔄 Code Review - PR submitted, awaiting review
• ✅ Completed - Feature done and deployed
• ❌ Blocked - Cannot proceed due to dependencies

Best Practices

• Create a feature file before starting development
• Update the file as you work (tasks, notes, decisions)
• Be specific with tasks (not "implement X", but "create Y service", "add Z endpoint")
• Document design decisions and lessons learned
• Link to PRs, commits, and code in the feature file

---

Important Notes

• Clean Architecture is mandatory: Always check dependencies flow inward
• MsTest required for backend: All changes must include tests
• Conventional Commits: Follow strictly for all commits
• Automatic deployment: Merging to main deploys to production
• Cross-project consistency: Keep frontend and backend in sync
• Feature tracking: Use docs/features/ for complex features

---

Last updated: May 31, 2025 This file can be updated as project conventions evolve. rn new User { Username = username, Email = email, CreatedAt = DateTime.UtcNow }; }

// Domain behavior
public void ChangeEmail(Email newEmail)
{
    Email = newEmail;
}

}

#### Value Object Example
```csharp
namespace GermanApp.Domain.ValueObjects;

public record Email
{
    public string Value { get; }
    
    public Email(string value)
    {
        if (!IsValid(value))
            throw new DomainException("Invalid email format");
        Value = value;
    }
    
    public static bool IsValid(string email)
    {
        // Validation logic
        return Regex.IsMatch(email, @"^[^@\s]+@[^@\s]+\.[^@\s]+$");    }
}

---

Important Notes

• Clean Architecture is mandatory: Always check dependencies flow inward
• MsTest required for backend: All changes must include tests
• Conventional Commits: Follow strictly for all commits
• Automatic deployment: Merging to main deploys to production
• Cross-project consistency: Keep frontend and backend in sync

---

Last updated: May 31, 2025 This file can be updated as project conventions evolve.