Architecture center · source revision pinned
Open Mercato Architecture: A Code-Evidenced System Atlas
Open Mercato is a modular, multi-tenant business-application foundation. A Next.js host assembles enabled modules around shared authentication, authorization, commands, data, queries, and events, then connects them to pluggable infrastructure and external systems. The atlas below follows those contracts without treating any mechanism as proof of deployment quality.
System map, not a security, performance, availability, or implementation certification.
Source snapshot:
ae856df1ecfc · ARCHITECTURE.md sections: 1, 2
Direct answer
How to read the whole system
Read downward from caller to application, cross-cutting services, enabled modules, infrastructure, and stores. Read sideways for extension and external-system boundaries. Each highlighted path names the scope it must preserve and the owner that still has to operate it.
Interactive system atlas
Choose one flow through the same system layers
A selection changes the highlight and URL. Every layer and ordered trace remains available in the document.
Browser and API consumer
external system
Next.js application routes
application local
Auth, RBAC, CRUD, commands, data, queries, and events
oss core
Enabled business modules
oss core
Cache, queue, search, scheduler, encryption
infrastructure package
PostgreSQL, Redis, and Meilisearch
external system
Provider package or external system
provider addon
Request carries authenticated tenant and organization scope into services.
Generated registries connect enabled modules to application routes and runtime services.
Command and DataEngine writes may emit events and maintain read-side indexes.
Persistent subscribers and workers move retryable work through the queue boundary.
Adapters and webhooks cross into provider or external-system responsibility.
Scoped read
- An application route resolves an enabled module page.
- Authentication establishes tenant and organization context.
- QueryEngine reads the scoped denormalized model.
- The server renders semantic content for the response.
Command and write
- The route checks access, parses input, and applies explicit scope.
- Mutation guards may block the operation before execution.
- CommandBus executes the registered mutation and records its audit context.
- DataEngine persists the record and schedules declared events or index work.
Event and background work
- The module declares a typed event contract.
- The event bus dispatches matching in-memory handlers.
- Persistent subscribers cross the queue boundary for retryable work.
- The worker must be idempotent and observed through failure and retry.
Cross-module extension
- The extending module chooses a stable cross-module surface instead of importing peer internals.
- A widget, interceptor, enricher, guard, command hook, event, or entity link carries the extension.
- Generation records the enabled contract in the runtime registry.
- The implementation still has to handle the peer module or optional surface being absent.
External integration
- The implementation defines which system owns each identifier and state transition.
- A provider adapter or route verifies the external contract and credentials.
- Queues or schedules isolate retryable and recurring work.
- Acknowledgement, deduplication, reconciliation, and outage recovery remain implementation obligations.
Mechanism, implication, limitation, owner
| Mechanism | Editorial implication | Limitation | Decision owner |
|---|---|---|---|
| Open Mercato is a modular, multi-tenant ERP and CRM foundation that teams self-host and extend. | 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. | Application architect |
| The documented system separates application routes, cross-cutting services, modules, pluggable infrastructure, and data stores. | Treat it as an “documented-convention” contract and confirm project-specific fit separately. | The mechanism does not prove performance, security, availability, compliance, or production readiness for a particular deployment. | Application architect |
Sources and method · 34 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.
Open Mercato is a modular, multi-tenant ERP and CRM foundation that teams self-host and extend.
- ID
section-01-product-foundation- Class
- product-fact
- Scope
- oss-core
- Source
- ARCHITECTURE.md ·
## 1. What is Open Mercato
The documented system separates application routes, cross-cutting services, modules, pluggable infrastructure, and data stores.
- ID
section-02-system-layers- Class
- product-fact
- Scope
- documented-convention
- Source
- ARCHITECTURE.md ·
## 2. High-Level Architecture
Browser and API consumer
- ID
node-browser- Class
- editorial-interpretation
- Scope
- external-system
- Source
- ARCHITECTURE.md ·
### System overview
Next.js application routes
- ID
node-application- Class
- product-fact
- Scope
- application-local
- Source
- apps/docs/docs/architecture/system-overview.mdx ·
## Runtime stack
Auth, RBAC, CRUD, commands, data, queries, and events
- ID
node-cross-cutting- Class
- editorial-interpretation
- Scope
- oss-core
- Source
- ARCHITECTURE.md ·
### Layers, top to bottom
Enabled business modules
- ID
node-modules- Class
- product-fact
- Scope
- oss-core
- Source
- apps/docs/docs/architecture/module-dependencies.mdx ·
## Module catalog
Cache, queue, search, scheduler, encryption
- ID
node-infrastructure- Class
- editorial-interpretation
- Scope
- infrastructure-package
- Source
- ARCHITECTURE.md ·
subgraph "Infrastructure (pluggable via DI)"
PostgreSQL, Redis, and Meilisearch
- ID
node-data- Class
- product-fact
- Scope
- external-system
- Source
- ARCHITECTURE.md ·
subgraph "Data"
Provider package or external system
- ID
node-provider- Class
- editorial-interpretation
- Scope
- provider-addon
- Source
- ARCHITECTURE.md ·
External integration provider
Request carries authenticated tenant and organization scope into services.
- ID
edge-request-scope- Class
- product-fact
- Scope
- oss-core
- Source
- packages/shared/src/lib/api/scoped.ts ·
export function withScopedPayload
Generated registries connect enabled modules to application routes and runtime services.
- ID
edge-module-contract- Class
- product-fact
- Scope
- oss-core
- Source
- packages/cli/src/lib/generators/module-registry.ts ·
modules.runtime.generated.ts
Command and DataEngine writes may emit events and maintain read-side indexes.
- ID
edge-write-side-effects- Class
- product-fact
- Scope
- oss-core
- Source
- packages/shared/src/lib/data/engine.ts ·
async emitOrmEntityEvent
Persistent subscribers and workers move retryable work through the queue boundary.
- ID
edge-background- Class
- product-fact
- Scope
- infrastructure-package
- Source
- packages/events/src/bus.ts ·
persistentSubscribers
Adapters and webhooks cross into provider or external-system responsibility.
- ID
edge-external- Class
- editorial-interpretation
- Scope
- provider-addon
- Source
- packages/webhooks/src/modules/webhooks/lib/adapter-registry.ts ·
export interface WebhookEndpointAdapter
An application route resolves an enabled module page.
- ID
flow-read-route- Class
- product-fact
- Scope
- oss-core
- Source
- apps/docs/docs/architecture/system-overview.mdx ·
## Request lifecycle
Authentication establishes tenant and organization context.
- ID
flow-read-scope- Class
- product-fact
- Scope
- oss-core
- Source
- packages/shared/src/lib/api/scoped.ts ·
export type ScopedContext
QueryEngine reads the scoped denormalized model.
- ID
flow-read-query- Class
- product-fact
- Scope
- oss-core
- Source
- packages/core/src/modules/query_index/lib/engine.ts ·
export class HybridQueryEngine
The server renders semantic content for the response.
- ID
flow-read-render- Class
- product-fact
- Scope
- oss-core
- Source
- apps/docs/docs/architecture/system-overview.mdx ·
## Runtime stack
The route checks access, parses input, and applies explicit scope.
- ID
flow-write-validate- Class
- product-fact
- Scope
- oss-core
- Source
- packages/shared/src/lib/crud/factory.ts ·
export function makeCrudRoute
Mutation guards may block the operation before execution.
- ID
flow-write-guard- Class
- product-fact
- Scope
- oss-core
- Source
- packages/shared/src/lib/crud/factory.ts ·
runMutationGuards
CommandBus executes the registered mutation and records its audit context.
- ID
flow-write-command- Class
- product-fact
- Scope
- oss-core
- Source
- packages/shared/src/lib/commands/command-bus.ts ·
export class CommandBus
DataEngine persists the record and schedules declared events or index work.
- ID
flow-write-effects- Class
- product-fact
- Scope
- oss-core
- Source
- packages/shared/src/lib/data/engine.ts ·
async emitOrmEntityEvent
The module declares a typed event contract.
- ID
flow-event-declare- Class
- product-fact
- Scope
- oss-core
- Source
- packages/shared/src/modules/events/factory.ts ·
export function createModuleEvents
The event bus dispatches matching in-memory handlers.
- ID
flow-event-emit- Class
- product-fact
- Scope
- oss-core
- Source
- packages/events/src/bus.ts ·
export function createEventBus
Persistent subscribers cross the queue boundary for retryable work.
- ID
flow-event-persist- Class
- product-fact
- Scope
- oss-core
- Source
- packages/events/src/bus.ts ·
persistentSubscribers
The worker must be idempotent and observed through failure and retry.
- ID
flow-event-operate- Class
- documented-convention
- Scope
- oss-core
- Source
- ARCHITECTURE.md ·
## 19. Queue and Background Jobs
The extending module chooses a stable cross-module surface instead of importing peer internals.
- ID
flow-extension-boundary- Class
- documented-convention
- Scope
- oss-core
- Source
- ARCHITECTURE.md ·
### Extensibility boundary: inject vs compose
A widget, interceptor, enricher, guard, command hook, event, or entity link carries the extension.
- ID
flow-extension-surface- Class
- product-fact
- Scope
- oss-core
- Source
- apps/docs/docs/framework/extensibility/current-surfaces.mdx ·
## API and mutation extension
Generation records the enabled contract in the runtime registry.
- ID
flow-extension-registry- Class
- product-fact
- Scope
- oss-core
- Source
- packages/cli/src/lib/generators/module-registry.ts ·
bootstrap-registrations.generated.ts
The implementation still has to handle the peer module or optional surface being absent.
- ID
flow-extension-absence- Class
- documented-convention
- Scope
- oss-core
- Source
- ARCHITECTURE.md ·
A module must work enabled or disabled.
The implementation defines which system owns each identifier and state transition.
- ID
flow-integration-authority- Class
- documented-convention
- Scope
- provider-addon
- Source
- ARCHITECTURE.md ·
### Webhooks
A provider adapter or route verifies the external contract and credentials.
- ID
flow-integration-adapter- Class
- product-fact
- Scope
- provider-addon
- Source
- packages/webhooks/src/modules/webhooks/lib/adapter-registry.ts ·
export interface WebhookEndpointAdapter
Queues or schedules isolate retryable and recurring work.
- ID
flow-integration-async- Class
- product-fact
- Scope
- provider-addon
- Source
- packages/scheduler/src/modules/scheduler/services/schedulerService.ts ·
export class SchedulerService
Acknowledgement, deduplication, reconciliation, and outage recovery remain implementation obligations.
- ID
flow-integration-reconcile- Class
- documented-convention
- Scope
- provider-addon
- Source
- ARCHITECTURE.md ·
Workers and subscribers MUST be idempotent.