Portfolio Portal
ADR proposed owner: Azwaan reviewed: 2026-07-05

ADR 0005: Introduce a Platform Services layer and consolidate reusable services

  • Status: proposed (recommendation from the Phase-D review; not yet adopted — no architecture changed)
  • Date: 2026-07-05
  • Deciders: Azwaan (pending)
  • Tags: structure, layering, consolidation, direction-change

This ADR records a recommended architectural direction change surfaced by the Phase-D Architecture Review. It is intentionally left proposed so existing architecture is unchanged. Adopt (or reject) deliberately; if adopted, it refines the layer model established in ADR 0002 / ADR 0003.

Context

The review found that the ecosystem’s reusable capabilities are architecturally sound but mis-placed:

  • The domain-agnostic Website Assessment engine lives inside inexisstudios (a venture marketing site), so consumers (outreachagent) depend on a venture repo for a platform capability (Risk R1).
  • Opportunity scoring is duplicated (pack score vs leadplatform’s own), and recommendation logic spans three layers (engine → pack → COP), creating consolidation debt and prospect-facing inconsistency risk (R2).
  • The Intelligence Platform layer conflates the knowledge platform (FIP) with the evaluation harness (lab), which behaves like a platform service.
  • There is no home for platform services, so reusable services are trapped in apps.

Decision (proposed)

  1. Introduce a Platform Services layer between Intelligence Products and Ventures/Apps, housing reusable services: Assessment, Opportunity/COP evaluation, Retrieval, and Evaluation (the lab).
  2. Extract the Assessment Service out of inexisstudios so consumers depend on a platform-service contract, not a venture repo.
  3. Establish the intelligence pack as the single source of truth for rules and scoring; retire leadplatform’s parallel opportunity score in favour of consuming the assessment/COP; pin the engine/COP recommendation mapping to the pack version.
  4. Tighten the Intelligence Platform layer to mean knowledge intelligence (FIP); reclassify the lab as a Platform Service (evaluation).
  5. Design the future Hermes feedback as one-way — publishing a new immutable pack version, never mutating a consumed pack — to prevent a producer/consumer cycle.

Options considered

Option Pros Cons
A (recommended): Platform Services layer + single source of truth Frees reuse; clean dependency directions; enables commercialisation; fewer future repos Requires extraction work; touches multiple repos
B: Keep services in apps, document coupling No refactor Reuse stays blocked; coupling & duplication compound
C: Merge everything into one platform repo Simplicity Loses immutability/contract boundaries; couples ventures

Consequences (if adopted)

  • Positive: reusable services get a home; consumers depend on contracts not ventures; one defensible score; ventures become thin compositions (service + pack); a clean base for automation and commercialisation.
  • Negative / trade-offs: extraction and migration effort; the layer model gains a layer (7); consumers must be re-pointed from venture APIs to platform-service contracts.
  • Affected pages (on adoption): Portfolio Overview layer model, system-of-systems, the Capability Registry owners, and inexisstudios/outreachagent/leadplatform digests.

Compliance / review

Adopt incrementally, one extraction at a time, each with its own follow-up ADR, preserving the evidence-first philosophy (Principle 8). Until adopted, this ADR remains proposed and the current architecture stands.