ai-instructions.mdc

---
description: This is the main entry point for AI-based development when working with this codebase, but also serves as a great reference for developers.
globs: 
alwaysApply: true
---

# Main entry point

This guide serves as the main entry point for AI-based development, providing structured access to all development guidelines and important documentation.

Always follow these rule files very carefully, as they have been crafted to ensure consistency and high-quality code.

## High-Level Problem Solving Strategy

1. Understand the problem deeply. Carefully read the instructions and think critically about what is required.
2. Always ask questions if something is unclear before starting to implement.
3. Investigate the codebase. Explore relevant files, search for key functions, and gather context.
4. Develop a clear, step-by-step plan. Break down the fix into manageable, incremental steps.
5. Before each code change, always consult the relevant rule files, to make sure you understand the rules and follow the conventions in the codebase.
   - Failure to follow the rules is the main reason for making unacceptable changes.
   - Before each code change list which rule files have been used to guide your response (e.g., `Rules consulted: [Commands](mdc:.ai-rules/backend/commands.mdc), [Unit and Integration Tests](mdc:.ai-rules/backend/unit-and-integration-tests.mdc)`).
6. Iterate until you are extremely confident the fix is complete and all tests pass.
7. After each change make sure you follow the rules in [Backend Rules](mdc:.ai-rules/backend/backend.mdc) or [Frontend Rules](mdc:.ai-rules/frontend/frontend.mdc), on how to correctly use the custom CLI tool for building, testing, and formatting the code.
   - Failure to use the custom CLI tool after each change is the second most common reason for making unacceptable changes.

## Overview of all guidelines rule files

### Backend Development
- [Backend Rules](mdc:.ai-rules/backend/backend.mdc) - Core guidelines for C# and .NET development:
  - [API Endpoints](mdc:.ai-rules/backend/api-endpoints.mdc) - Guidelines for minimal API endpoints.  
  - [Commands](mdc:.ai-rules/backend/commands.mdc) - Implementation of state-changing operations using CQRS commands.
  - [Domain Modeling](mdc:.ai-rules/backend/domain-modeling.mdc) - Implementation of DDD aggregates, entities, and value objects.
  - [External Integrations](mdc:.ai-rules/backend/external-integrations.mdc) - Implementation of integration to external services.
  - [Queries](mdc:.ai-rules/backend/queries.mdc) - Implementation of data retrieval operations using CQRS queries.
  - [Repositories](mdc:.ai-rules/backend/repositories.mdc) - Persistence abstractions for aggregates.
  - [Strongly Typed IDs](mdc:.ai-rules/backend/strongly-typed-ids.mdc) - Type-safe DDD identifiers for domain entities.
  - [Telemetry Events](mdc:.ai-rules/backend/telemetry-events.mdc) - Standardized observability event patterns.
  - [Unit and Integration Tests](mdc:.ai-rules/backend/unit-and-integration-tests.mdc) - Test suite patterns for commands, queries, and domain logic.

### Frontend Development
- [Frontend Rules](mdc:.ai-rules/frontend/frontend.mdc) - Core guidelines for React/TypeScript:
  - [Form with Validation](mdc:.ai-rules/frontend/form-with-validation.mdc) - Forms with validation and API integration using TanStack Query.
  - [Modal Dialog](mdc:.ai-rules/frontend/modal-dialog.mdc) - Modal dialog implementation patterns.
  - [React Aria Components](mdc:.ai-rules/frontend/react-aria-components.mdc) - Usage of shared component library.
  - [TanStack Query API Integration](mdc:.ai-rules/frontend/tanstack-query-api-integration.mdc) - Data fetching and mutation patterns.
  - [Translations](mdc:.ai-rules/frontend/translations.mdc) - Internationalization implementation for UI text.

### Azure Infrastructure
- [Infrastructure Rules](mdc:.ai-rules/infrastructure/infrastructure.mdc) - Cloud infrastructure guidelines.

### Developer CLI
- [Developer CLI Rules](mdc:.ai-rules/developer-cli/developer-cli.mdc) - Guide lines for extending the custom Developer CLI.

### Other Rules
- [Git Commit Rules](mdc:.ai-rules/other/git-commits.mdc) - Guidelines for creating commit messages.
- [Pull Request Rules](mdc:.ai-rules/other/pull-request.mdc) - Guidelines for creating pull requests.
- [Creating and Updating AI Rules](mdc:.ai-rules/other/creating-and-updating-ai-rules.mdc) - Guidelines for creating and updating AI rules.

## Project Structure

This is a mono repository with multiple self-contained systems (SCS), each being a small monolith. All SCSs follow the same structure. Use this overview to gain an understanding of the codebase structure.

- [.github](mdc:.github): GitHub workflows and other GitHub artifacts.
- [application](mdc:application): Contains application code:
  - [account-management](mdc:application/account-management): An SCS for tenant and user management:
    - [WebApp](mdc:application/account-management/WebApp): A React, TypeScript SPA.
    - [Api](mdc:application/account-management/Api): .NET 9 minimal API.
    - [Core](mdc:application/account-management/Core): .NET 9 Vertical Sliced Architecture.
    - [Workers](mdc:application/account-management/Workers): A .NET Console job.
    - [Tests](mdc:application/account-management/Tests): xUnit tests for backend.
  - [back-office](mdc:application/back-office): An empty SCS that will be used to create tools for Support and System Admins:
    - [WebApp](mdc:application/back-office/WebApp): A React, TypeScript SPA.
    - [Api](mdc:application/back-office/Api): .NET 9 minimal API.
    - [Core](mdc:application/back-office/Core): .NET 9 Vertical Sliced Architecture.
    - [Workers](mdc:application/back-office/Workers): A .NET Console job.
    - [Tests](mdc:application/back-office/Tests): xUnit tests for backend.
  - [AppHost](mdc:application/AppHost): .NET Aspire project for orchestrating SCSs and Docker containers. Never run directly—typically running in watch mode.
  - [AppGateway](mdc:application/AppGateway): Main entry point using .NET YARP as reverse proxy for all SCSs.
  - [shared-kernel](mdc:application/shared-kernel): Reusable .NET backend shared by all SCSs.
  - [shared-webapp](mdc:application/shared-webapp): Reusable frontend shared by all SCSs.
- [cloud-infrastructure](mdc:cloud-infrastructure): Bash and Azure Bicep scripts (IaC).
- [developer-cli](mdc:developer-cli): A .NET CLI tool for automating common developer tasks.