# Understanding Feature

## Overview

Features in FlexBase are organized around **CRUD operations** (Create, Read, Update, Delete) with two distinct patterns: **Command-based operations** for data modification and **Query-based operations** for data retrieval.

## Feature Categories

### 1. Command-Based Features (Data Modification)

These features use **Controllers** and **Handlers** to modify data:

#### **Insert Features** - Create New Data

* **Purpose**: Add new entities to the system
* **Flow**: `Controller → Service → Command Handler → Domain Model → Database`
* **Example**: `AddOrder`, `CreateProduct`, `RegisterUser`
* **HTTP Method**: `POST`

#### **Update Features** - Modify Existing Data

* **Purpose**: Update existing entities
* **Flow**: `Controller → Service → Command Handler → Domain Model → Database`
* **Example**: `UpdateOrder`, `EditProduct`, `ModifyUser`
* **HTTP Method**: `PUT`

#### **Delete Features** - Remove Data

* **Purpose**: Permanently remove entities
* **Flow**: `Controller → Service → Command Handler → Domain Model → Database`
* **Example**: `DeleteOrder`, `RemoveProduct`, `DeactivateUser`
* **HTTP Method**: `DELETE`

#### **Soft Delete Features** - Mark as Deleted

* **Purpose**: Mark entities as deleted without removing them
* **Flow**: `Controller → Service → Command Handler → Domain Model → Database`
* **Example**: `SoftDeleteOrder`, `ArchiveProduct`, `DeactivateUser`
* **HTTP Method**: `PUT`

### 2. Query-Based Features (Data Retrieval)

These features use **Controllers** and **Query projects** to retrieve data:

#### **GetById Features** - Retrieve Single Entity by ID

* **Purpose**: Get one specific entity by its unique identifier
* **Flow**: `Controller → Service → Query Handler → Database → Response`
* **Example**: `GetOrderById`, `GetProductById`, `GetUserById`
* **HTTP Method**: `GET`

#### **GetSingle Features** - Retrieve Single Entity by Criteria

* **Purpose**: Get one entity based on specific criteria
* **Flow**: `Controller → Service → Query Handler → Database → Response`
* **Example**: `GetOrderByNumber`, `GetProductBySku`, `GetUserByEmail`
* **HTTP Method**: `GET`

#### **GetList Features** - Retrieve Multiple Entities

* **Purpose**: Get a collection of entities
* **Flow**: `Controller → Service → Query Handler → Database → Response`
* **Example**: `GetOrders`, `GetProducts`, `GetUsers`
* **HTTP Method**: `GET`

#### **GetPagedList Features** - Retrieve Paginated Results

* **Purpose**: Get entities with pagination support
* **Flow**: `Controller → Service → Query Handler → Database → Response`
* **Example**: `GetOrdersPaged`, `GetProductsPaged`, `GetUsersPaged`
* **HTTP Method**: `GET`

## Control Flow Comparison

### Command Flow (Insert/Update/Delete/SoftDelete)

```
API Request → Controller → Service → Command Handler → Domain Model → Database → Event Publishing → Response
```

**Key Characteristics:**

* **Modifies data** in the system
* **Uses Command Handlers** for business logic
* **Publishes events** after successful operations
* **Returns success/failure** status

#### **Eventual vs Non-Eventual Provision**

**Non-Eventual (Synchronous) Flow:**

```
API Request → Controller → Service → Command Handler → Domain Model → Database → Response
```

* **Immediate Response**: User gets response after data is saved
* **Synchronous Processing**: All operations complete before response
* **Use Case**: Critical operations requiring immediate confirmation
* **Example**: Payment processing, user registration

**Eventual (Asynchronous) Flow:**

```
API Request → Controller → Service → Command Handler → Domain Model → Database → Event Publishing → Response
```

* **Immediate Acknowledgment**: User gets acknowledgment, processing continues in background
* **Asynchronous Processing**: Events trigger additional processing
* **Use Case**: Operations that can be processed later
* **Example**: Email notifications, report generation, data synchronization

### Query Flow (GetById/GetSingle/GetList/GetPagedList)

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

**Key Characteristics:**

* **Reads data** from the system
* **Uses Query Handlers** for data retrieval
* **No events published** (read-only operations)
* **Returns data** or empty results

## Implementation Pattern

### Command Features

* **Controller**: `YourEntityController_Add.cs`, `YourEntityController_Update.cs`
* **Handler**: `AddYourEntityHandler.cs`, `UpdateYourEntityHandler.cs`
* **Message**: `AddYourEntityCommand.cs`, `UpdateYourEntityCommand.cs`
* **DTO**: `AddYourEntityDto.cs`, `UpdateYourEntityDto.cs`

### Query Features

* **Controller**: `YourEntityController_GetById.cs`, `YourEntityController_GetList.cs`
* **Query**: `GetYourEntityByIdQuery.cs`, `GetYourEntityListQuery.cs`
* **DTO**: `GetYourEntityDto.cs`, `YourEntityListDto.cs`

## Benefits of This Approach

* **Clear Separation**: Commands modify data, Queries retrieve data
* **Scalability**: Can scale read and write operations independently
* **Maintainability**: Each feature has a single responsibility
* **Testability**: Easy to test each component in isolation
* **Performance**: Optimized for different operation types

***

**Next Steps**: Learn how to implement these features in your FlexBase applications by exploring the specific feature implementation guides! 🚀


---

# 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/solution-structure/getting-started/features/understanding-feature.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.