> For the complete documentation index, see [llms.txt](https://docs.flexbase.in/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flexbase.in/solution-structure/getting-started/features/understanding-feature.md).

# 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! 🚀