The Open Mercato GuideEditorial guide · not official documentation
Menu
GitHubPL

Concept family 01 · module assembly

Open Mercato Modular Architecture and Package Boundaries

Open Mercato assembles business capability from enabled modules and generated registries. Package direction, declared dependencies, stable DI keys, edition boundaries, and application ownership decide what can be replaced safely. Ejecting source is possible only for declared modules and transfers ongoing upgrade responsibility to the application team.

Module independence supports replaceability; it does not make every customization upgrade-safe.

Source snapshot:

ae856df1ecfc · ARCHITECTURE.md sections: 3, 4, 6, 25, 26, 28, 29

Direct answer

Position in the system

This family explains how source packages become the enabled module graph consumed by the host application. It owns assembly and boundaries, not project-specific architecture decisions.

Package and module dependency graph

Shared sits below UI and Core; infrastructure packages and providers expose separate contracts; the app selects modules and generated glue.

Package and module dependency graphShared sits below UI and Core; infrastructure packages and providers expose separate contracts; the app selects modules and generated glue.
01

Shared, UI, Core, infrastructure, provider, Enterprise, and application code occupy different package layers with downward dependency direction.

documented-convention

02

The CLI discovers enabled modules, writes generated registries, and rejects missing declared dependencies during generation.

oss-core

03

Request-scoped services are resolved by stable string keys from an Awilix container.

oss-core

04

Enterprise modules are source-separated and opt-in; they are not universally present in an OSS application.

enterprise-opt-in

05

A standalone app enables package or app-local modules and can prefer overrides or UMES before taking ownership of ejected source.

application-local

06

Generated registries are derived artifacts with distinct versioned and ephemeral locations; editing them by hand breaks regeneration ownership.

documented-convention

07

Business capability is distributed across Core and supporting modules rather than one inseparable application layer.

oss-core

From modules.ts to a running registry

A generation-time trace makes dependency failure visible before runtime.

  1. A standalone app enables package or app-local modules and can prefer overrides or UMES before taking ownership of ejected source.

    documented-conventionapplication-local

  2. The CLI discovers enabled modules, writes generated registries, and rejects missing declared dependencies during generation.

    product-factoss-core

  3. Generated registries are derived artifacts with distinct versioned and ephemeral locations; editing them by hand breaks regeneration ownership.

    documented-conventiondocumented-convention

  4. Request-scoped services are resolved by stable string keys from an Awilix container.

    documented-conventionoss-core

Assembly contracts and responsibilities

Assembly contracts and responsibilities
MechanismEditorial implicationLimitationDecision owner
Shared, UI, Core, infrastructure, provider, Enterprise, and application code occupy different package layers with downward dependency direction.Treat it as an “documented-convention” contract and confirm project-specific fit separately.This is a committed engineering convention. A custom application can still violate it and must be reviewed separately.Module and platform maintainer
The CLI discovers enabled modules, writes generated registries, and rejects missing declared dependencies during generation.Treat it as an “oss-core” contract and confirm project-specific fit separately.The mechanism does not prove performance, security, availability, compliance, or production readiness for a particular deployment.Module and platform maintainer
Request-scoped services are resolved by stable string keys from an Awilix container.Treat it as an “oss-core” contract and confirm project-specific fit separately.This is a committed engineering convention. A custom application can still violate it and must be reviewed separately.Module and platform maintainer
Enterprise modules are source-separated and opt-in; they are not universally present in an OSS application.Treat it as an “enterprise-opt-in” contract and confirm project-specific fit separately.The surface is optional or separately configured and must not be read as universally enabled.Module and platform maintainer
A standalone app enables package or app-local modules and can prefer overrides or UMES before taking ownership of ejected source.Treat it as an “application-local” contract and confirm project-specific fit separately.This is a committed engineering convention. A custom application can still violate it and must be reviewed separately.Module and platform maintainer
Generated registries are derived artifacts with distinct versioned and ephemeral locations; editing them by hand breaks regeneration ownership.Treat it as an “documented-convention” contract and confirm project-specific fit separately.This is a committed engineering convention. A custom application can still violate it and must be reviewed separately.Module and platform maintainer
Business capability is distributed across Core and supporting modules rather than one inseparable application layer.Treat it as an “oss-core” contract and confirm project-specific fit separately.This is a committed engineering convention. A custom application can still violate it and must be reviewed separately.Module and platform maintainer

Footguns and failure modes

Enterprise modules are source-separated and opt-in; they are not universally present in an OSS application.

The surface is optional or separately configured and must not be read as universally enabled.

Inspect pinned source

Generated registries are derived artifacts with distinct versioned and ephemeral locations; editing them by hand breaks regeneration ownership.

This is a committed engineering convention. A custom application can still violate it and must be reviewed separately.

Inspect pinned source
Sources and method · 7 evidence records

Every fact, node, connector, and flow step has a stable ID, claim class, source locator, scope, limitation, and pinned revision. A local verifier checks every file and locator and ensures sections 1–33 are covered exactly once.

  • Shared, UI, Core, infrastructure, provider, Enterprise, and application code occupy different package layers with downward dependency direction.

    ID
    section-03-monorepo-boundaries
    Class
    documented-convention
    Scope
    documented-convention
    Source
    ARCHITECTURE.md · ## 3. Monorepo Structure

  • The CLI discovers enabled modules, writes generated registries, and rejects missing declared dependencies during generation.

    ID
    section-04-module-discovery
    Class
    product-fact
    Scope
    oss-core
    Source
    packages/cli/src/lib/generators/module-registry.ts · export async function generateModuleRegistry

  • Request-scoped services are resolved by stable string keys from an Awilix container.

    ID
    section-06-di-container
    Class
    documented-convention
    Scope
    oss-core
    Source
    ARCHITECTURE.md · ## 6. Dependency Injection

  • Enterprise modules are source-separated and opt-in; they are not universally present in an OSS application.

    ID
    section-25-editions
    Class
    product-fact
    Scope
    enterprise-opt-in
    Source
    ARCHITECTURE.md · ## 25. Editions: OSS and Enterprise

  • A standalone app enables package or app-local modules and can prefer overrides or UMES before taking ownership of ejected source.

    ID
    section-26-standalone
    Class
    documented-convention
    Scope
    application-local
    Source
    ARCHITECTURE.md · ## 26. Building a Standalone App

  • Generated registries are derived artifacts with distinct versioned and ephemeral locations; editing them by hand breaks regeneration ownership.

    ID
    section-28-generated-files
    Class
    documented-convention
    Scope
    documented-convention
    Source
    packages/cli/src/lib/generators/module-registry.ts · addAutoGeneratedComment(sourceFile, 'registry')

  • Business capability is distributed across Core and supporting modules rather than one inseparable application layer.

    ID
    section-29-business-modules
    Class
    documented-convention
    Scope
    oss-core
    Source
    ARCHITECTURE.md · ## 29. Business Modules Overview