Shared Libraries - Overview

Purpose

Define what may be shared across islands without creating package sprawl or shared mutable domain coupling.

This document follows:

• docs/migration/02-island-boundaries-and-performance.md
• docs/migration/03-architecture-review-checklist-template.md

Internal Shared Package Cap

Maximum internal shared packages: 3.

Package	Responsibility	Explicitly Not Allowed
atraxion/contracts	Cross-island API/event DTOs, schemas, contract validation helpers	Domain entities, ORM mappings, business workflows
atraxion/integration-sdk	Reusable connector primitives (HTTP/FTP wrappers, retry/backoff, idempotency, signatures)	Platform/supplier business rules
atraxion/foundation	Stable primitives (Money, IDs, clocks, typed value objects)	Island-specific services or repositories

Any additional package requires a formal ADR and must pass the extraction gate checklist.

What Stays Island-Local

The following stay inside the owning island:

• Domain entities (Article, Order, Vehicle, Customer, etc.)
• Business workflows (pricing, fitment scoring, checkout, ERP orchestration)
• Repositories and database migrations
• Platform/supplier specific connector behavior

Rule: no shared mutable domain bundle.

Connector Reuse Model

Do not create one package per supplier or platform by default.

Preferred model:

1. Implement adapters inside the owning island.
2. Reuse only connector primitives through atraxion/integration-sdk.
3. Extract to shared package only after reuse and stability criteria are proven.

Extraction Criteria (Must All Be True)

1. Reused by at least 2 islands.
2. API expected to stay stable for 6+ months.
3. Contains no app-specific entities/workflows.
4. Change passed the ADR architecture checklist.

Versioning and Release

• Shared packages use semantic versioning.
• Island apps pin package versions and upgrade independently.
• Contract changes in atraxion/contracts require compatibility notes and migration guidance.

Testing Expectations

Package	Required Tests
atraxion/contracts	Contract/schema validation tests and backward-compatibility checks
atraxion/integration-sdk	Unit tests for retry/idempotency/signature behavior + integration smoke tests
atraxion/foundation	Unit tests for all value objects and deterministic behavior

Migration Notes

Legacy bundle-first guidance (core-bundle, article-bundle, vehicle-bundle) is superseded.

During migration:

1. Move shared domain entities back to owning islands.
2. Keep only stable primitives and contracts in shared packages.
3. Update cross-island communication to sync REST + async events using contract DTOs.