New Service Implementation

Use this template when building a new service module in the operations repository. It covers entity definitions, service interface, method specifications, persistence layer, and module configuration.

When to Use

• Creating a new domain module (new package under cards.arda.operations).
• Defining entities, value types, and service interfaces for a new capability.
• Specifying persistence schema, universe classes, and module wiring.

Document Sections

1. Overview — Service summary, module location, related documents.
2. Entity Definitions (ED) — Sealed interfaces, data classes, validation rules, computed properties.
3. Domain Value Types (VT) — Enums, sealed interfaces, value objects.
4. Service Interface (SI) — Interface contract, core and module-specific methods.
5. Method Specifications (MS) — Parameters, qualifier behavior, pre/post-conditions, side effects, errors.
6. Persistence Specifications (PS) — Table definitions, record classes, universe methods, indexes.
7. Module Configuration (MC) — Entry point, dependencies, constructed components.
8. Testing Requirements — Unit, integration, and harness patterns.

Requirement ID Conventions

Prefix	Category	Example
ED	Entity Definition	ED-INV-001
VT	Value Type	VT-INV-001
SI	Service Interface	SI-INV-001
MS	Method Specification	MS-INV-001
PS	Persistence Specification	PS-INV-001
MC	Module Configuration	MC-INV-001
VR	Validation Rule	VR-001

Template

The full template is extensive. Key sections are shown below; see the complete source at workspace/knowledge-base/templates/incremental-service/service-implementation-requirements.md.

Entity Definition Block

### ED-CODE-001: `EntityName`

- **Description**: What this entity represents in the domain.
- **Sealed Interface**: `EntityName` extends `EntityPayload`
- **Implementation**: `EntityName.Entity` data class
- **Metadata Class**: `EntityNameMetadata` extends `ScopedMetadata`

#### Properties

| Property | Type | Required | Default | Description |
|---|---|---|---|---|
| `eId` | `EntityId` (`UUID`) | Yes | Generated | Unique entity identifier |
| `name` | `String` | Yes | - | Description |
| `property` | `Type` | Yes/No | `default` | Description |

#### Validation Rules

| Rule ID | Condition | Error | Message |
|---|---|---|---|
| VR-001 | `name.isBlank()` | `AppError.ArgumentValidation` | "Name is required" |

Method Specification Block

### MS-CODE-001: `methodName`

- **Signature**: `suspend fun methodName(params): Result<ReturnType>`
- **Purpose**: What this method accomplishes.

#### Behavior by Qualifier

| Qualifier | Behavior |
|---|---|
| **LAX** | Flexibility, upsert, skip validation |
| **STRICT** | Verify consistency, fail on mismatch |
| **PROPAGATE** | Cascade changes to related entities |

#### Error Conditions

| Condition | Error Type | Error Message |
|---|---|---|
| Entity not found | `AppError.NotFound` | "Entity [id] not found" |
| Validation failure | `AppError.ArgumentValidation` | "field: message" |

Persistence Block

### PS-CODE-001: `TableName` Table

- **Table Object**: `TABLE_NAME` extends `ScopedTable`
- **Record Class**: `EntityNameRecord` extends `ScopedRecord`

#### Column Definitions

| Column Name | Kotlin Property | Type | Nullable | Description |
|---|---|---|---|---|
| `e_id` | (inherited) | `uuid` | No | Entity identifier |
| `tenant_id` | (inherited) | `uuid` | No | Tenant scope |
| `column_name` | `propertyName` | `db_type` | Yes/No | Description |

Module Configuration Block

### MC-CODE-001: Module Entry Point

- **Extension Function**: `Application.moduleName(cfgProvider, authentication, ...): ServiceName`

#### Dependencies

| Dependency | Type | Purpose |
|---|---|---|
| `cfgProvider` | `ConfigurationProvider` | Application configuration |
| `authentication` | `Authentication` | Auth context |

Activity diagrams (PlantUML) should accompany complex method specifications, and component diagrams should illustrate the module structure.