> 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/flexbase-mcp-ai-prompts/flexbase-api-guide-prompts.md).

# Flexbase API Guide Prompts

> Ready-to-use prompts for implementing FlexBase API patterns, conventions, and best practices.

**Important:** Module names should be in **PLURAL** form (e.g., `Applications`, `Candidates`, `Orders`, `Customers`).

***

## How to Use

Tell your AI agent what API task you need. It will load the relevant patterns and conventions automatically.

**Example prompts you can give your AI agent:**

```
Implement the complete Orders feature — DTOs, mapper, query, handler
```

```
Review all Update DTOs to ensure they have the mandatory Id property
```

```
Create a List/Output DTO for the Customer entity
```

```
Add concurrency handling to the CreateBooking handler
```

```
Implement workflow states for the Order entity
```

```
Set up email notifications using SendGrid
```

***

## Critical Rules

These are enforced automatically by the agent:

* **NEVER remove `Id` from Update/SoftDelete/Delete DTOs** — causes silent API failures
* **All ID properties are `string` type** — never Guid or UUID
* **Protected setters** — use domain factory methods, not direct assignment in handlers
* **EF-agnostic queries** — use FlexBase query patterns, not EF Core–specific APIs
* **Workflow states** — use FlexState pattern, not string `Status` columns

***

## Task Catalog

### DTO Tasks

| Task                                 | Goal                                                    |
| ------------------------------------ | ------------------------------------------------------- |
| **Review DTO rules**                 | Summarize all DTO patterns and identify violations      |
| **Create List/Output DTO**           | Create a proper output DTO for an entity                |
| **Create Lookup DTO**                | Create a minimal DTO for lookups/dropdowns              |
| **Create Input DTO (Create/Update)** | Create input DTOs with validation annotations           |
| **Create Action DTO**                | Create DTOs for actions (Submit, Approve, Reject, etc.) |
| **Fix DTO violations**               | Review and fix all DTO rule violations in the project   |
| **Complete empty DTOs**              | Fill in empty/incomplete DTOs based on domain models    |

### Mapper Tasks

| Task                               | Goal                                                |
| ---------------------------------- | --------------------------------------------------- |
| **Create Domain Mapper**           | Map Entity ↔ EntityDto                              |
| **Create Feature Mapper (Output)** | Map Entity → Feature DTO                            |
| **Create Feature Mapper (Input)**  | Map Input DTO → Entity                              |
| **Simplify mappers**               | Remove unnecessary complexity from existing mappers |

### Query & Handler Tasks

| Task                           | Goal                                            |
| ------------------------------ | ----------------------------------------------- |
| **Create Query**               | Implement query with filtering, sorting, paging |
| **Implement Complete Feature** | Full feature: DTO + Mapper + Query/Handler      |

### Domain Model Tasks

| Task                         | Goal                                                |
| ---------------------------- | --------------------------------------------------- |
| **Review Domain Models**     | Verify domain models follow conventions             |
| **Verify Project Structure** | Check folder organization matches FlexBase patterns |

### Workflow & Concurrency Tasks

| Task                             | Goal                                                          |
| -------------------------------- | ------------------------------------------------------------- |
| **Implement FlexState Workflow** | Create workflow states with transitions and role-based access |
| **Add Concurrency Handling**     | Add optimistic concurrency with logical checks                |
| **Make Subscriber Idempotent**   | Add duplicate detection to event subscribers                  |
| **Capacity-Based Booking**       | Implement capacity checks with state transitions              |

### Provider & DataStore Tasks

| Task                      | Goal                                                                 |
| ------------------------- | -------------------------------------------------------------------- |
| **Integrate AI Provider** | Set up AI capabilities (chat, embeddings, streaming)                 |
| **Implement RAG**         | Set up vector store + AI provider for retrieval-augmented generation |
| **Email Notifications**   | Configure email provider for notifications                           |
| **Document Store**        | Set up CosmosDB, MongoDB, or other document stores                   |
| **File Storage**          | Set up Azure Blob, AWS S3, or GCP Storage                            |
| **Multiple AI Providers** | Configure multiple AI providers for different use cases              |
| **Cache Store**           | Set up Redis or other cache providers                                |

### Review Tasks

| Task                        | Goal                                         |
| --------------------------- | -------------------------------------------- |
| **Complete Project Review** | Full audit against all FlexBase API patterns |
| **Sync DTOs with API**      | Compare UI interfaces with API DTOs          |

***

## Usage Tips

1. **Replace placeholders:**
   * `[EntityName]` → Your actual entity name (e.g., `Candidate`, `Order`)
   * `[ModuleName]` → Your actual module name (e.g., `Orders`, `Customers`)
   * `[ProjectName]` → Your actual project name
2. **Common workflow:**
   * Implement complete feature (DTO + Mapper + Handler/Query)
   * Review and fix any violations
   * Generate UI pages from the Blazor/Angular/React guide

***

## Related

* **After building APIs:** [Implementation Completion](/flexbase-mcp-ai-prompts/implementation-completion-prompts.md)
* **Build UI:** [Blazor FluentUI](/flexbase-mcp-ai-prompts/blazor-fluent-ui-guide-prompts.md) | [Angular](/flexbase-mcp-ai-prompts/angular-ui-guide-prompts.md) | [React](/flexbase-mcp-ai-prompts/react-js-ui-guide-prompts.md)