Pull Request Review Guidelines

Criteria for reviewing code contributions in the Arda backend ecosystem. These criteria ensure contributions adhere to core design patterns and architectural principles.

1. Domain Modeling and Immutability

• Immutability: Are all domain objects (Payloads, Value Objects) immutable data classes?
• Optics: Does the entity define @optics to allow clean immutable updates?
• Payloads: Does the data class implement EntityPayload?
• Value Objects: Are existing value objects used (Money.Value, DateTime) instead of primitives where applicable?
• Data Authority DSL: If creating a standard CRUD endpoint, is DataAuthorityEndpointNew.reify used instead of manual coding?

2. Bitemporal Persistence

• Universe Pattern: Does the service layer interact with the database only via a Universe? No direct Exposed DAO access.
• Time Coordinates:
  • Red flag: Is TimeCoordinates.now() called inside a loop? It must be passed in from the top level.
  • Are effective (valid time) and recorded (transaction time) handled correctly?
• Validation: Does the Universe or Validator enforce business rules before create/update?

3. State Management (State Engine)

• Lifecycle: Are complex state transitions defined in a Lifecycle engine rather than ad-hoc if/else blocks?
• Guards: Are sensitive transitions protected by guard operations?
• Signals: Are signals meaningful enums (OrderSignal.SUBMIT) representing user or system intent?

4. Service Layer and Actions

• Action Pattern: Are mutations encapsulated as Action objects (inheriting from AbstractSimpleAction)?
• Transactions: Is action execution wrapped in inTx(db) to ensure atomicity?
• Red flag: Is transaction { } used directly in the service layer? It should be wrapped in an Action or Universe.

5. Error Handling

• Functional Approach: Is Result<T> used instead of throwing exceptions?
• Error Mapping: Are infrastructure errors correctly normalized to AppError?
• Red flag: Are there try/catch blocks? They should be runCatching { } or Result.failure().

6. API and Security

• DTOs: Are request/response objects separate from internal domain entities?
• Security: Are routes registered in configureSecureRoutes unless they explicitly must be public?

7. Testing and Quality

• Unit Tests: Are complex domain logic and calculations covered by unit tests?
• Integration Tests: Does Module.kt initialization allow easy dependency injection in tests?
• API Tests: Are .bru files updated or added for new endpoints?