Technical Design Patterns

Create comprehensive technical design documents that guide implementation of ABP Framework features.

When to Use

• Designing REST API endpoints and contracts
• Planning database schemas and indexes
• Creating Technical Specification Documents (TSD)
• Documenting Architecture Decision Records (ADRs)
• Defining DTO structures and validation rules

Technical Design Document Structure

A complete TSD for an ABP feature includes:

1. Overview - Feature summary and scope
2. API Contract - Endpoints, methods, DTOs
3. Database Schema - Tables, columns, indexes, relationships
4. Permissions - Required permissions and role mappings
5. Validation Rules - Input constraints
6. Caching Strategy - What to cache, TTL
7. Open Questions - Items needing clarification

API Contract Template

## API: {Resource}

### Overview
| Attribute | Value |
|-----------|-------|
| Base Path | `/api/app/{resources}` |
| Authentication | Required |
| Rate Limit | 100/min |

### Endpoints

| Method | Path | Description | Permission | Request | Response |
|--------|------|-------------|------------|---------|----------|
| GET | `/{resources}` | List with pagination | `{Project}.{Resources}` | `Get{Resource}ListInput` | `PagedResultDto<{Resource}Dto>` |
| GET | `/{resources}/{id}` | Get by ID | `{Project}.{Resources}` | - | `{Resource}Dto` |
| POST | `/{resources}` | Create new | `{Project}.{Resources}.Create` | `CreateUpdate{Resource}Dto` | `{Resource}Dto` |
| PUT | `/{resources}/{id}` | Update existing | `{Project}.{Resources}.Edit` | `CreateUpdate{Resource}Dto` | `{Resource}Dto` |
| DELETE | `/{resources}/{id}` | Soft delete | `{Project}.{Resources}.Delete` | - | - |

### DTOs

#### {Resource}Dto (Output)
```json
{
  "id": "guid",
  "property1": "string",
  "property2": 0,
  "creationTime": "datetime",
  "lastModificationTime": "datetime"
}

CreateUpdate{Resource}Dto (Input)

{
  "property1": "string (required, max 100)",
  "property2": "number (optional, min 0)"
}

Get{Resource}ListInput (Query)

{
  "filter": "string (optional)",
  "sorting": "string (optional, e.g., 'name asc')",
  "skipCount": "number (default 0)",
  "maxResultCount": "number (default 10, max 100)"
}

## Database Schema Template

```markdown
## Entity: {Name}

### Table: {TableName}

| Column | Type | Nullable | Default | Constraints | Description |
|--------|------|----------|---------|-------------|-------------|
| `Id` | `uuid` | NO | `gen_random_uuid()` | PK | Unique identifier |
| `Name` | `varchar(100)` | NO | - | - | Display name |
| `Email` | `varchar(255)` | NO | - | UNIQUE | Contact email |
| `Status` | `smallint` | NO | `0` | - | Enum: 0=Active, 1=Inactive |
| `ParentId` | `uuid` | YES | - | FK | Reference to parent |
| `CreationTime` | `timestamp` | NO | `now()` | - | ABP audit field |
| `CreatorId` | `uuid` | YES | - | - | ABP audit field |
| `LastModificationTime` | `timestamp` | YES | - | - | ABP audit field |
| `LastModifierId` | `uuid` | YES | - | - | ABP audit field |
| `IsDeleted` | `boolean` | NO | `false` | - | ABP soft delete |
| `DeleterId` | `uuid` | YES | - | - | ABP audit field |
| `DeletionTime` | `timestamp` | YES | - | - | ABP audit field |

### Indexes

| Name | Columns | Type | Purpose |
|------|---------|------|---------|
| `PK_{Table}` | `Id` | Primary | Primary key |
| `IX_{Table}_Email` | `Email` | Unique | Email lookup |
| `IX_{Table}_Name` | `Name` | B-tree | Name search |
| `IX_{Table}_ParentId` | `ParentId` | B-tree | Parent lookup |
| `IX_{Table}_IsDeleted` | `IsDeleted` | Partial (false) | Active records filter |

### Relationships

| Relationship | Type | Target | FK Column | On Delete |
|--------------|------|--------|-----------|-----------|
| Parent | N:1 | `{Parent}` | `ParentId` | SET NULL |
| Children | 1:N | `{Child}` | - | CASCADE |

Permission Design Template

## Permissions: {Resource}

### Permission Definitions

| Permission | Display Name | Parent |
|------------|--------------|--------|
| `{Project}.{Resources}` | {Resource} Management | - |
| `{Project}.{Resources}.Create` | Create {Resource} | `{Project}.{Resources}` |
| `{Project}.{Resources}.Edit` | Edit {Resource} | `{Project}.{Resources}` |
| `{Project}.{Resources}.Delete` | Delete {Resource} | `{Project}.{Resources}` |

### Role Mapping

| Role | View | Create | Edit | Delete |
|------|------|--------|------|--------|
| Admin | ✓ | ✓ | ✓ | ✓ |
| Manager | ✓ | ✓ | ✓ | - |
| User | ✓ | - | - | - |

Architecture Decision Record (ADR) Template

# ADR-{NNN}: {Decision Title}

**Status**: Proposed | Accepted | Deprecated | Superseded
**Date**: YYYY-MM-DD
**Deciders**: [List of people involved]

## Context

[Describe the issue motivating this decision. What is the problem we're trying to solve?]

## Decision Drivers

- [Driver 1: e.g., performance requirement]
- [Driver 2: e.g., maintainability concern]
- [Driver 3: e.g., team expertise]

## Considered Options

1. **[Option 1]** - [Brief description]
2. **[Option 2]** - [Brief description]
3. **[Option 3]** - [Brief description]

## Decision

We will use **[Option X]** because [rationale].

## Consequences

### Positive
- [Benefit 1]
- [Benefit 2]

### Negative
- [Drawback 1]
- [Drawback 2]

### Risks
- [Risk 1 and mitigation]

## Related Decisions

- [ADR-XXX: Related decision]

Validation Rules Template

## Validation: CreateUpdate{Resource}Dto

| Property | Rules | Error Message |
|----------|-------|---------------|
| `Name` | Required, MaxLength(100) | "Name is required" / "Name cannot exceed 100 characters" |
| `Email` | Required, EmailFormat, MaxLength(255) | "Valid email is required" |
| `Phone` | Optional, PhoneFormat | "Invalid phone format" |
| `Amount` | Required, Range(0, 999999.99) | "Amount must be between 0 and 999999.99" |

Caching Strategy Template

## Caching: {Resource}

| Operation | Cache Key | TTL | Invalidation |
|-----------|-----------|-----|--------------|
| GetById | `{resource}:{id}` | 5 min | On Update, Delete |
| GetList | `{resource}:list:{hash}` | 1 min | On Create, Update, Delete |
| GetCount | `{resource}:count` | 1 min | On Create, Delete |

### Cache Implementation
- **Provider**: Redis (distributed)
- **Serialization**: JSON
- **Compression**: None (small payloads)

Quality Checklist

Before finalizing technical design:

• All CRUD endpoints defined with permissions
• DTOs match entity properties (no entity exposure)
• Database schema includes all ABP audit columns
• Indexes defined for query patterns
• Validation rules specified for all inputs
• Relationships and cascade behavior defined
• Caching strategy considered for read-heavy operations
• Open questions documented

References

• references/api-examples.md - Real API contract examples
• references/schema-examples.md - Database schema examples