> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR-010: Core–Platform Foundation Dependency Boundary

> Status: Accepted Date: 2026-04-12 Participants: Platform Architecture Team, Jeremy Bloom

**Status:** Accepted\
**Date:** 2026-04-12\
**Participants:** Platform Architecture Team, Jeremy Bloom

***

## Context

The platform has 12 domain cores (CE, CL, FA, FM, FW, GR, HR, IT, LO, PM, PF, RH) plus Platform Foundation (PF). Without explicit dependency rules, cores would start importing from each other, creating a dependency tangle that makes testing, reasoning, and future extraction impossible. A clear boundary rule was needed.

## Options Considered

### Option A: Free imports (no restrictions)

* **How it works:** Any core can import from any other core.
* **Pros:** Fastest initial development; no discipline required.
* **Cons:** Creates circular dependencies; makes cores impossible to test in isolation; tightly couples unrelated business domains (HR ↔ FA ↔ CL etc.); refactoring becomes exponentially expensive as the graph grows.
* **Why not chosen:** Unacceptable for a platform intended to scale to 12+ cores and be potentially extracted to microservices.

### Option B: Layered architecture (cores can import from "lower" cores)

* **How it works:** Cores are arranged in layers; upper layers can import lower layers. E.g., CL can import PM, PM can import HR, etc.
* **Pros:** Structured hierarchy; avoids circular dependencies.
* **Cons:** Still couples cores to each other; adding a new dependency requires reordering layers; complex to enforce and reason about.
* **Why not chosen:** Still creates core-to-core coupling that makes testing and isolation difficult.

### Option C: PF-only dependency (chosen) ✓

* **How it works:** All domain cores (CE, CL, FA, etc.) may only import from `@/platform/*` (PF) and shared utilities (`@/shared/*`). No direct core-to-core imports. Cross-core communication uses the Platform Integration Layer (`@/platform/*`), event contracts, and API contracts. CL is explicitly downstream (no other core depends on CL).
* **Pros:** Clean separation of business domains; cores are independently testable; PF acts as a stable contract boundary; cross-core changes go through explicit integration contracts.
* **Cons:** Requires more upfront design for cross-core features; integration layer must be designed before features can use it; some perceived overhead for simple lookups.
* **Why chosen:** The only architecture that keeps 12 business domains independently testable and maintainable as the platform grows. PF acts as a shared kernel pattern.

## Decision

Domain cores depend only on `@/platform/*` (PF) and `@/shared/*`. No direct imports across core boundaries (e.g., `src/cores/hr` cannot import `src/cores/fa`). Cross-core communication is via: (1) Platform Integration Layer at `@/platform/*`, (2) event contracts in `docs/architecture/integrations/EVENT_CONTRACTS.md`, (3) API contracts in `docs/architecture/integrations/API_CONTRACTS.md`. CL is explicitly downstream — no other core may depend on CL. This is enforced by `npm run check-architecture` in CI.

Exception: CL tables may reference `pm_encounters.id` via database FK per ADR-002. This is the only approved DB-level cross-core FK.

## Consequences

### Positive

* Each core can be tested in isolation
* Architecture violations caught automatically in CI
* Clear ownership: each core team owns their slice
* Platform Integration Layer provides stable contracts for cross-core features

### Negative

* Cross-core features require platform layer design work upfront
* New integration patterns require an ADR

### Mitigations

* `check-architecture` CI gate catches violations before merge
* `@/platform/clinical`, `@/platform/scheduling`, `@/platform/types` provide pre-built integration contracts for common CL/PM patterns
* Integration contract template (`INTEGRATION_CONTRACT_TEMPLATE.md`) for new contracts

## Related Documents

* [Constitution §1 Architecture & Module Boundaries](../../../constitution.md)
* [ADR-002](ADR-002-cl-pm-cross-core-foreign-keys.md) — CL–PM cross-core FK exception
* [docs/architecture/integrations/CROSS\_CORE\_INTEGRATIONS.md](../integrations/CROSS_CORE_INTEGRATIONS.md)
* [AGENTS.md §Architecture Rules](../../../AGENTS.md)