# Intent.Application.Contracts

Generates C# interface definitions for your Application Services, applying the Interface Segregation Principle to promote clean separation between service contracts and their implementations.

## What is the Intent.Application.Contracts Module?

This module generates service interface files (`IXxxService.cs`) that define the contract for application services. By separating the interface from implementation, you achieve:

- **Testability**: Mock service dependencies easily in unit tests
- **Flexibility**: Swap implementations without changing consumers
- **Interface Segregation**: Clients depend on abstractions, not concrete implementations
- **Dependency Injection**: Register interfaces in DI containers for loose coupling

The module works alongside `Intent.Application.ServiceImplementations` (traditional service pattern) to provide the complete service layer.

## What This Module Generates

For each Service modeled in the Services Designer, this module generates:

**Service Interface File** (`IXxxService.cs`):
```csharp
using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

namespace MyApp.Application.Interfaces
{
    /// <summary>
    /// Service documentation from model
    /// </summary>
    public interface ICustomerService
    {
        /// <summary>
        /// Operation documentation from model
        /// </summary>
        Task<CustomerDTO> GetCustomerById(Guid id, CancellationToken cancellationToken = default);
        
        Task<List<CustomerDTO>> GetAllCustomers(CancellationToken cancellationToken = default);
        
        Task CreateCustomer(CreateCustomerDTO dto, CancellationToken cancellationToken = default);
        
        Task UpdateCustomer(Guid id, UpdateCustomerDTO dto, CancellationToken cancellationToken = default);
        
        Task DeleteCustomer(Guid id, CancellationToken cancellationToken = default);
    }
}
```

### Generated Interface Characteristics

**Automatic Naming Convention:**
- Removes common suffixes (`RestController`, `Controller`, `Service`) from model name
- Prefixes with `I` for interface naming convention
- Example: `CustomerService` model → `ICustomerService` interface

**Async by Default:**
- All operations generate as `async` methods by default
- Automatically includes `CancellationToken` parameter with default value
- Return types wrapped in `Task<T>` or `Task`

**Type Resolution:**
- Resolves DTO types from `Intent.Application.Dtos` module
- Resolves Enum types from Application Contracts or Domain layer
- Handles generic type parameters from modeled operations
- Smart namespace resolution to avoid ambiguous references

## How to Use

### 1. Model Services in Services Designer

In Intent Architect's Services Designer:

1. Create a new Service (e.g., `CustomerService`)
2. Add operations (methods) to the service
3. Define parameters with types (DTOs, primitives, Domain types)
4. Define return types for operations
5. Optionally add documentation to services, operations, and parameters

### 2. Software Factory Execution

When you run the Software Factory:

1. **Intent.Application.Contracts** generates the interface definition
2. **Intent.Application.ServiceImplementations** generates the implementation
3. **Intent.Application.DependencyInjection** registers the interface and implementation in DI

### 3. Consume Services via Dependency Injection

The generated interfaces can be injected into constructors:

```csharp
public class CustomerController
{
    private readonly ICustomerService _customerService;
    
    public CustomerController(ICustomerService customerService)
    {
        _customerService = customerService;
    }
    
    public async Task<IActionResult> GetCustomer(Guid id, CancellationToken cancellationToken)
    {
        var customer = await _customerService.GetCustomerById(id, cancellationToken);
        return Ok(customer);
    }
}
```

## Integration with Other Modules

### Intent.Application.ServiceImplementations

When used with `Intent.Application.ServiceImplementations`:

- **Contracts module** generates `ICustomerService` interface
- **ServiceImplementations module** generates `CustomerService` class implementing the interface
- Both work together to provide complete service layer

Example implementation structure:
```csharp
public class CustomerService : ICustomerService
{
    // Constructor injection of repositories, AutoMapper, etc.
    
    public async Task<CustomerDTO> GetCustomerById(Guid id, CancellationToken cancellationToken)
    {
        // Implementation logic
    }
}
```

### Intent.Application.Dtos

The Contracts module depends on DTO types generated by `Intent.Application.Dtos`:

- Parameter types reference generated DTOs
- Return types reference generated DTOs
- Collection types use `List<T>` by default (configurable)

### Intent.AspNetCore.Controllers.Dispatch.ServiceContract

When using ASP.NET Core Controllers:

- **Contracts module** generates the interface
- **Controllers.Dispatch.ServiceContract module** generates controllers that inject and call the interface
- Clean separation between HTTP concerns and business logic

Example controller dispatch:
```csharp
[ApiController]
[Route("api/customers")]
public class CustomersController : ControllerBase
{
    private readonly ICustomerService _customerService;
    
    public CustomersController(ICustomerService customerService)
    {
        _customerService = customerService;
    }
    
    [HttpGet("{id}")]
    public async Task<ActionResult<CustomerDTO>> GetCustomer(Guid id, CancellationToken cancellationToken)
    {
        return await _customerService.GetCustomerById(id, cancellationToken);
    }
}
```

### Intent.Application.Contracts.Clients

For client-side service interfaces (e.g., calling external APIs):

- **Contracts module** generates server-side service interfaces
- **Contracts.Clients module** generates client-side service proxy interfaces
- Enables consistent programming model across service boundaries

## Related Modules

- **Intent.Application.ServiceImplementations** - Generates concrete service classes implementing these interfaces
- **Intent.Application.MediatR** - Alternative implementation pattern using CQRS with Commands and Queries
- **Intent.Application.Dtos** - Generates DTO types used in interface signatures
- **Intent.Application.DependencyInjection** - Registers service interfaces and implementations in DI container
- **Intent.AspNetCore.Controllers.Dispatch.ServiceContract** - Generates controllers that dispatch to service interfaces
- **Intent.Application.Contracts.Clients** - Generates client-side service proxy interfaces
- **Intent.FastEndpoints.Dispatch.Services** - FastEndpoints integration dispatching to service interfaces

## External Resources

- [Interface Segregation Principle (SOLID)](https://en.wikipedia.org/wiki/Interface_segregation_principle)
- [Dependency Injection in .NET](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection)
- [Testing with Mocks and Stubs](https://learn.microsoft.com/dotnet/core/testing/unit-testing-best-practices)