Glossary and Domain Contracts

This document defines shared domain language and contract ownership across attunelogic-api, attunelogic-mobile, and attunelogic-service.

Why this exists

• Keep terminology consistent across backend, mobile, and web.
• Prevent duplicate business logic definitions in multiple repos.
• Reduce regressions caused by contract drift.

Source of truth ownership

• Domain rules and transitions: attunelogic-api
• API request and response contracts: attunelogic-api
• Client rendering and interaction patterns: attunelogic-mobile, attunelogic-service
• Architecture decisions and rationale: attunelogic-docs

Canonical terms

• Job: Top-level business object that groups execution work.
• Leg: A unit of execution within a job lifecycle, including status transitions.
• Shift: Time-bound assignment block for workers and operations.
• Task: Actionable work item that may be required, optional, or auto-completed.
• Stage: Coarse-grained progression marker for a workflow.
• Status: Fine-grained state used for execution, automation, and reporting.

Contract rules

1. API remains the contract authority for domain status transitions.
2. Mobile and service clients consume contract data; they do not redefine domain rules.
3. Response shape changes require compatibility handling and rollout notes.
4. New statuses or stages must be documented here and mapped in all client displays.
5. Tenant-specific behavior must be implemented through configuration with safe defaults.

Change process for statuses and stages

When adding or changing a status or stage:

1. Update canonical definitions in attunelogic-api.
2. Add transition and validation behavior in API services/controllers.
3. Update client-facing labels, filters, and workflows in mobile and service.
4. Add or update test coverage across affected repositories.
5. Record rationale with an ADR if behavior or architecture meaningfully changes.