Skip to content

ADR-001: Explicit application lifecycle

Status

Accepted

Context

Balyze revolves around the concept of tracking job applications over time. Early in the project, the need emerged to clearly define how an application evolves from creation to completion.

Without an explicit lifecycle, applications risk becoming ambiguous objects:

  • partially submitted
  • inconsistently editable
  • difficult to reason about historically

A clear lifecycle is required to:

  • preserve historical accuracy
  • enforce consistent business rules
  • avoid implicit or scattered state handling

Decision

An explicit and finite lifecycle is defined for the Application domain entity.

The lifecycle is represented by a dedicated enum and enforced through domain services.

The following states are defined:

  • draft
  • submitted
  • in_progress
  • rejected
  • accepted

State transitions are explicit, unidirectional, and controlled.

Once an application is submitted:

  • structural data is frozen
  • contextual data remains editable
  • the submission timestamp is set and immutable

Returning to a previous state (e.g. back to draft) is not allowed.

Rationale

This decision favors clarity and predictability over maximum flexibility.

Key considerations:

  • a submitted application represents a point-in-time intent
  • historical data must not be altered retroactively
  • implicit state handling increases long-term complexity
  • explicit transitions simplify reasoning, testing, and maintenance

By constraining the lifecycle early, future extensions can be added safely without breaking existing assumptions.

Alternatives considered

Implicit lifecycle (status as a loose flag)

Rejected because:

  • rules become scattered across the codebase
  • editability constraints are harder to enforce
  • application state becomes ambiguous over time

Allow returning to draft

Rejected because:

  • it breaks historical consistency
  • it complicates editability rules
  • it introduces edge cases with timestamps and documents

Automatic or time-based transitions

Deferred. The current scope does not justify the added complexity.

Consequences

Positive

  • clear domain boundaries
  • consistent enforcement of rules
  • simpler services and policies
  • improved long-term maintainability

Trade-offs

  • reduced flexibility for edge cases
  • lifecycle changes require explicit decisions

These trade-offs are considered acceptable at the current stage.

  • Domain overview
  • Application lifecycle
  • Application editability rules