# Architecture Requirements

Phase: design
Enforcement: informational (graduating to blocking Q3 2026)

## ARCH-001: API Contract First

All new or modified REST APIs MUST have an updated OpenAPI/Swagger spec BEFORE implementation begins.

**Rule:** If a PR adds or changes an endpoint, the corresponding `openapi.yaml` or Swagger annotation must be updated in the same PR.

**Test:** Diff check — if files in `src/**/controller/**` or `src/**/api/**` changed, verify `**/openapi*.yaml` or `**/swagger*.yaml` also changed.

## ARCH-002: Service Boundary Respect

Changes to a service MUST NOT directly import or reference internal classes from another service's module.

**Rule:** Cross-service communication happens through APIs, events, or SDK interfaces only. No direct classpath coupling between service modules.

**Test:** Import scan — flag imports crossing module boundaries (e.g., `import com.reltio.server.internal.*` from SDK module).

## ARCH-003: Breaking Change Protocol

Any breaking API change (removed field, changed type, renamed endpoint) MUST include:
1. A deprecation annotation on the old path
2. A migration note in the PR description
3. A minimum 30-day dual-support window

**Rule:** Breaking changes without deprecation path are rejected.

**Test:** Detect removed/renamed public API methods or fields in diff. Flag if no `@Deprecated` annotation present.

## ARCH-004: Multi-Repository Coordination

For changes spanning multiple repositories (e.g., SDK + Server), the design spec MUST list all affected repos and the order of deployment.

**Rule:** Multi-repo PRs must reference a shared Jira ticket and declare deployment sequence.

**Test:** If PR description references multiple repos, verify Jira link present.