api-and-interface-design

Define the Retrofit interface before implementing it, declaring suspend functions with annotations like @POST, @GET, and @PATCH for each endpoint. Use structured request bodies and typed response models rather than raw JSON strings.

Keep DTOs with serialization annotations like @Serializable and @SerialName in the data layer, and map them to plain domain models used by UI and business logic. This prevents Retrofit or Room annotations from leaking into domain packages.

Use sealed interfaces when states carry different associated data, such as InProgress with an assignee or Completed with a timestamp. Sealed types give compile-time exhaustive when checks and smart casting, unlike enums or boolean flags.

Prefer addition over modification by adding new fields as optional parameters with default values in data classes. Existing parsers and callers continue to work while new consumers can use the added fields.

Value classes like @JvmInline value class TaskId prevent accidentally passing a UserId where a TaskId is expected, catching mix-ups at compile time. They add type safety with no runtime allocation overhead.

Validate user input at system boundaries, such as in the ViewModel before calling repositories, and validate API responses inside the repository before mapping to domain models. Internal code can then assume data is already safe.