ADR-0005: Two-layer architecture (Platform Core + Business Packs)

ADR-0005: Two-layer architecture (Platform Core + Business Packs)

Status: Accepted Date: 2026-04-20

Context

The platform is designed to serve multiple verticals. E-commerce is first, but the same runtime should host agents for (e.g.) customer support, operations, or internal tooling at a later date. If we build e-commerce concepts directly into the runtime, we pay a migration cost at every future vertical.

At the same time, a fully generic platform with no opinionated building blocks is unpleasant to work with — every new vertical ends up reimplementing the same communication patterns and tool scaffolding.

Decision

Two layers:

1. Platform Core — business-agnostic. Defines the runtime, orchestrator, memory system, tool registry, event bus, context assembler, and the types that everything else uses. Published as @agent-platform/core and future runtime siblings (@agent-platform/runtime, etc.).
2. Business Packs — vertical-specific. Defines agents, their tool sets, integrations with third-party services, and domain events. Each pack is a separate package (e.g. a future @agent-platform/ecommerce).

The dependency arrow only ever points from Business Packs into Platform Core. Platform Core has zero knowledge of any vertical.

Consequences

• Adding a new vertical is additive: a new package, no edits to core.
• Any e-commerce concept that leaks into core is a code-review smell. Reviewers have a clear rule to enforce.
• Shared patterns across verticals (e.g., a common CRM interface) get their own package — not a third architectural layer, just a sibling Business Pack that others can depend on.
• Small upfront cost: the first vertical costs slightly more to build because we have to resist the temptation to put its types in core.
• Business Packs can evolve independently and ship separately.

Consequences for the current repo

• packages/core/ is the first Platform Core package. Its types carry no e-commerce-specific vocabulary.
• packages/ will host both core and business packs side by side. Distinguishing them is by name, not directory — keeps the workspace simple.

Alternatives considered

• Monolithic (single package): faster now, much slower later, painful to extract at vertical #2.
• Three layers (core + common-business + vertical): premature. We have one vertical and no observed need for shared-business-logic. Revisit at vertical #2 or #3.
• Plugin system without formal package split: harder to enforce the dependency direction and harder to version independently.
• Keep vertical-agnostic logic separate but deploy as one thing: mixes concerns. Keeping packages distinct even when deployed together preserves the discipline.