# ADR 014: Shared Platform Services Strategy

**Status**: Accepted (interfaces defined in Phase 0/1; full implementation Phase 3)
**Date**: 2026-04-19
**Deciders**: Architecture Lead, Platform PO

---

## Context

Every product vertical needs the same building blocks: identity, logging, metrics, tracing, notifications, search, cache, queue, feature flags, ratelimiting, config, i18n. If each module rolls its own, the system fragments and customer-specific adapters (ADR 010, 013) cannot plug in cleanly.

## Decision

A small, fixed set of **shared platform services** is owned by the Platform team. Each service is consumed through a **typed interface**. Implementations are pluggable via composition profiles (ADR 013).

Phase 0/1 scope (this repo, today):

- `platform-logging` (logger facade — see ADR 016)
- `platform-config` (env + composition profile loader)
- `platform-features` (feature flag interface; first impl reads from profile/DB)

Phase 3 scope (later):

- `platform-auth`, `platform-metrics`, `platform-tracing`
- `platform-cache`, `platform-queue`, `platform-search`
- `platform-notifications`, `platform-ratelimit`, `platform-i18n-runtime`

## Rules this decision creates

1. Cross-cutting capabilities (logging, config, flags, etc.) are obtained from the platform service, not re-implemented in feature modules.
2. Adding a new platform service requires (a) an interface, (b) a default implementation, (c) at least one contract test, (d) docs.
3. A platform service must have at least two viable implementations (or a credible plan for one) before becoming load-bearing — otherwise it is just a wrapper.
4. Customer-specific behaviour wires into platform services via the composition profile, never by direct import.

## Consequences

### Forbidden

- Logging via `console.*` in non-trivial code paths once the logger facade exists (Phase 1 migration; remaining call sites are tracked).
- Reading env vars directly inside feature modules; the platform-config layer owns env parsing.
- Inventing a parallel notification / queue / cache mechanism inside a feature module.

### Accepted

- A small platform team becomes responsible for the shared services and their evolution.
- Some extra ceremony adding a new cross-cutting capability.

## Related

- ADR 010 — Product core vs customer adapter
- ADR 013 — Composition profiles
- ADR 016 — Logging and observability facade