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
```bash
# 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
```bash
# 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
```csharp
// 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.*