Overview

This section contains the seven interconnected document templates and best-practice guides that form the Arda Product Development System’s backbone for specifying, implementing, and evolving backend Kotlin services.

Overview

Arda backend services follow a layered architecture: entities defined as sealed interfaces, service interfaces with qualifier-aware methods, persistence via Universe classes, and module entry points for dependency injection. The documents in this section specify the conventions for each layer and provide reviewable templates.

Document Map

Feature Idea / Change Request
        │
        ▼
[Requirements List] ─────────────────────► [Requirements Best Practices]
        │
        ▼
[Specification] (task-level)
        │
        ├── New service? ──────────────► [Implementation Requirements]
        │                                      │
        │                                      ▼
        │                               [Implementation Best Practices]
        │
        └── Existing service? ────────► [Incremental Requirements]
                                               │
                                               ▼
                                        [Incremental Best Practices]

When to Use Each Document

Situation	Document
Documenting what a feature must do (business perspective)	Requirements List
Reviewing a requirements list for quality	Requirements Best Practices
Specifying an implementation task for an agent or engineer	Specification
Designing a new Kotlin service module from scratch	Implementation Requirements
Reviewing a service implementation specification	Implementation Best Practices
Specifying a change to an existing deployed service	Incremental Requirements
Reviewing an incremental change specification	Incremental Best Practices

Key Conventions

• All entities use the sealed interface + Entity data class pattern.
• All fallible methods return Result<T> using the AppError hierarchy.
• Mutation operations accept a MutationQualifier (LAX, STRICT, PROPAGATE).
• Persistence uses bitemporal storage; all operations carry a time: Long parameter.
• Module entry points support nullable injected dependencies for testing.

Related Process Documents

• Test Case Methodology — Derive test cases from these specifications
• Kotlin coding standards — see the kotlin-coding skill
• Task execution workflow — see the implementation-task skill