# Flexbase Control Flow

## 🎯 Overview

This document explains the complete control flow for Flexbase features - from API call to execution completion. We'll cover one **Insert (POST)** and one **Query (GET)** example.

***

## 📝 Insert Feature Flow: AddOrder

### **1. API Request**

```
POST /api/Orders/AddOrder
Content-Type: application/json

{
  "customerId": "12345",
  "totalAmount": 299.99,
  "orderItems": [...]
}
```

### **2. Controller Layer**

```csharp
[HttpPost]
[Route("AddOrder")]
public async Task<IActionResult> AddOrder([FromBody] AddOrderDto dto)
{
    return await RunService(201, dto, _processOrdersService.AddOrder);
}
```

**What happens:** Controller receives request, validates DTO, calls service

### **3. Service Layer**

```csharp
public async Task<IActionResult> AddOrder(AddOrderDto dto)
{
    var command = new AddOrderCommand { Dto = dto };
    await _addOrderHandler.Execute(command, _serviceBusContext);
    return new OkResult();
}
```

**What happens:** Service creates command, calls handler

### **4. Command Handler**

```csharp
public async Task Execute(AddOrderCommand cmd, IFlexServiceBusContext serviceBusContext)
{
    // 1. Initialize repository
    _repoFactory.Init(cmd.Dto);
    
    // 2. Call domain method
    _model = _flexHost.GetDomainModel<Order>().AddOrder(cmd);
    
    // 3. Persist to database
    _repoFactory.GetRepo().InsertOrUpdate(_model);
    await _repoFactory.GetRepo().SaveAsync();
    
    // 4. Publish events
    await this.Fire(EventCondition, serviceBusContext);
}
```

**What happens:** Handler orchestrates the operation, calls domain, persists data, publishes events

### **5. Domain Method (Your Business Logic)**

```csharp
public virtual Order AddOrder(AddOrderCommand cmd)
{
    // Your business rules
    if (cmd.Dto.TotalAmount <= 0)
        throw new BusinessException("Invalid amount");
    
    // Apply business logic
    this.Convert(cmd.Dto);
    this.SetAdded(cmd.Dto.GetGeneratedId());
    this.CalculateTotal();
    
    return this;
}
```

**What happens:** Domain validates business rules, applies logic, returns entity

### **6. Database Persistence**

```csharp
_repoFactory.GetRepo().InsertOrUpdate(_model);
await _repoFactory.GetRepo().SaveAsync();
```

**What happens:** Entity Framework saves to database

### **7. Event Publishing**

```csharp
await this.Fire(EventCondition, serviceBusContext);
```

**What happens:** Domain events published to message bus for side effects

### **8. Response**

```
HTTP 201 Created
Location: /api/Orders/{orderId}
```

***

## 🔍 Query Feature Flow: GetOrders

### **1. API Request**

```
GET /api/Orders/GetOrders?status=Pending
```

### **2. Controller Layer**

```csharp
[HttpGet]
[Route("GetOrders")]
public async Task<IActionResult> GetOrders([FromQuery] GetOrdersQuery query)
{
    return await RunService(200, query, _processOrdersService.GetOrders);
}
```

**What happens:** Controller receives request, calls service

### **3. Service Layer**

```csharp
public async Task<IActionResult> GetOrders(GetOrdersQuery query)
{
    var result = _getOrdersHandler.Fetch();
    return new OkObjectResult(result);
}
```

**What happens:** Service calls query handler

### **4. Query Handler**

```csharp
public override IEnumerable<GetOrdersDto> Fetch()
{
    return _repoFactory.GetRepo()
        .FindAll<Order>()
        .Where(o => o.Status == query.Status)
        .Include(o => o.Customer)
        .SelectTo<GetOrdersDto>()
        .ToList();
}
```

**What happens:** Handler executes optimized database query with projection

### **5. Database Query**

```sql
-- Generated SQL (optimized)
SELECT 
    o.Id,
    c.Name AS CustomerName,
    o.TotalAmount,
    o.Status,
    o.OrderDate
FROM Orders o
LEFT JOIN Customers c ON o.CustomerId = c.Id
WHERE o.Status = @Status
```

**What happens:** Only required fields fetched from database

### **6. Projection Mapping**

```csharp
// AutoMapper automatically maps to DTO
CreateMap<Order, GetOrdersDto>()
    .ForMember(dest => dest.CustomerName, opt => opt.MapFrom(src => src.Customer.Name));
```

**What happens:** Database results mapped to DTO

### **7. Response**

```json
HTTP 200 OK
[
  {
    "id": "12345",
    "customerName": "John Doe",
    "totalAmount": 299.99,
    "status": "Pending",
    "orderDate": "2024-01-15T10:30:00Z"
  }
]
```

***

## 🔄 Complete Flow Summary

### **Insert Flow:**

```
API Request → Controller → Service → Command Handler → Domain Method → Database → Events → Response
```

### **Query Flow:**

```
API Request → Controller → Service → Query Handler → Database Query → Projection → Response
```

***

## 🎯 Key Points

### **Insert Features:**

* **Command Pattern** - Encapsulates operation
* **Domain Logic** - Business rules in domain layer
* **Event Publishing** - Side effects handled asynchronously
* **Transaction Management** - Automatic rollback on errors

### **Query Features:**

* **Projection-Based** - Only fetch required fields
* **Optimized SQL** - Generated automatically
* **Type Safety** - Compile-time validation
* **Performance** - Database-level optimization

### **Common Benefits:**

* **Separation of Concerns** - Each layer has single responsibility
* **Testability** - Each layer can be tested independently
* **Maintainability** - Clear, readable code structure
* **Consistency** - Same pattern across all features

***

*This control flow ensures reliable, maintainable, and performant enterprise applications with Flexbase.*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flexbase.in/thinking-in-flexbase/flexbase-control-flow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.