Architecture built for safe extension
Open Mercato uses a Modular Monolith architecture. It provides the deployment simplicity of a single application with the strict boundary isolation typically found in microservices. This is the structural "North Star" that allows AI agents to write production-grade code without creating a maintenance nightmare.
Watch the Open Mercato Architecture
One deployable application, with modules that keep UI, API, and schema changes isolated and predictable.
The building blocks
The Open-Closed Principle (OCP)
The biggest risk in custom development is "framework lock-in"—where you cannot update the core because your custom changes are scattered everywhere. We solve this with our Open-Closed Approach.
- Zero-Modification Core: The core modules remain untouched in the src/modules directory.
- The Overlay Layer: All custom logic, UI overrides, and new entities live in the src/apps directory.
- Build-Time Resolution: Our generators scan both directories at build-time. If a file exists in the Overlay, it replaces or extends the Core equivalent.
"The core idea is to be open for extensions but closed for core modifications, achieved through build-time generators that scan enabled modules and allow overrides."
Source: OM - Architecture Webinar
AI-Assisted Engineering (AIE) Ready
Standard architectures confuse AI agents because of context fragmentation. Open Mercato is built to be "read" by LLMs.
- Context-Rich Mono-repo: By keeping the UI, API, and Schema in a single, well-structured repository, we provide agents with the full relationship context they need.
- AGENTS.MD: Each module contains a machine-readable specification that acts as a "guardrail" for AI generation.
"Open Mercato provides the 'plumbing'—auth, multi-tenancy, RBAC, and encrypted data layers—which are notoriously difficult to prompt correctly and securely."
Source: Open Mercato FAQ
The Request Flow: Command Pattern & Dependency Injection
We ensure architectural consistency through a strict request flow:
- Awilix DI Container: We use Dependency Injection to manage service lifecycles. This allows you to "swap" a core service for a custom one simply by re-registering it in the container.
- Command Pattern: Every write operation is a "Command." This is why we can offer Audit Logs and Undo/Redo functionality out of the box.
- Event-Driven side effects: Modules communicate via an internal event bus. When a deal.created event fires, any other module (like a custom Notification module) can react without being tightly coupled.
Enterprise-Grade Security Architecture
We don't just secure the perimeter; we secure the data at the cell level.
- Field-Level Encryption (FLE): We use AES-GCM encryption for sensitive data.
- Tenant-Scoped KMS: Each tenant (customer) has their own encryption context
- "Your data is also safe at rest because the fields in the database they are encrypted with AES so it's a super strong encryption. And by the way you can choose which fields on which tables entities are encrypted." (Source: OM - Architecture Webinar).
- Row-Level Scoping: Every database query is automatically piped through a global filter that injects tenantId and organizationId, preventing data leaks between customers.
How to install Open Mercato
The Trade-off
Open Mercato requires a shift in mindset. It is not a "wild west" where you write code anywhere. You must adhere to the Overlay Pattern and Dependency Injection. While this has a slightly steeper learning curve for junior developers, it is the only way to ensure a system remains maintainable after 24 months of heavy AI-assisted feature growth.
Ready-made implementation scenarios
The "Zero-Knowledge" HIPAA/FinTech Portal
Scenario: You need to build a patient management system or a financial portal where even database administrators cannot read sensitive PII (Personally Identifiable Information).
- The Blueprint:
- Encrypted Vault Module: Activate Tenant-Scoped Field-Level Encryption.
- Security Config: Tag fields like social_security_number or medical_history in your entity definition.
- The "Secret Sauce": Use our KMS integration to ensure keys are unique per tenant.
- Technical Edge: > "Your data is also safe at rest because the fields in the database they are encrypted with AES so it's a super strong encryption... it's fully configurable." (Source: OM - Architecture Webinar)
- Business Outcome: Pass a Level 3 Security Audit in the first week of development.
The "Niche" Vertical CRM (e.g., Solar Installation)
Scenario: A client needs a CRM that doesn't just manage "contacts" but tracks "Roof Pitch," "Sun Exposure," and "Grid Interconnect Status."
- The Blueprint:
- Overlay Override: Extend the core CRM Foundation without touching the base code.
- Custom Fields Layer: Define the "Solar" specific fields via the UI or AGENTS.MD instructions for your AI.
- Workflow Engine: Attach a state machine to the Opportunity entity to handle the unique solar permitting process.
- Technical Edge: > "A custom fields layer allows runtime-defined models, enabling users to add custom fields to core entities with different field editors and types." (Source: OM - Architecture Webinar)
- Business Outcome: Deliver a 100% bespoke industry solution with the stability of a battle-tested core.
The AI-Automated Logistics Dispatcher
Scenario: A logistics company wants an AI to automatically assign drivers to loads based on complex vehicle tracking data and custom business rules.
- The Blueprint:
- Custom Module: Generate a Logistics module AI Context: Feed AGENTS.MD to Cursor/Claude to generate the dispatch logic that respects the organizationId hierarchy.
- Event-Driven Integration: Subscribe to the order.created event to trigger the AI-assignment service.
- Technical Edge: > "Open Mercato provides the 'plumbing'—auth, multi-tenancy, RBAC, and encrypted data layers—which are notoriously difficult to prompt correctly and securely." (Source: Open Mercato FAQ)
- Business Outcome: Shift from "CRUD coding" to "AI Engineering," delivering complex automation in under 15 minutes of prompting.
The Multi-Tier Partner Portal (B2B2B)
Scenario: A manufacturer needs a portal where Distributors can manage their own Dealers, but the Manufacturer retains global visibility.
- The Blueprint:
- Directory Module: Utilize the Multi-hierarchical organizations (Tree structure).
- Scoped Access: Use the built-in filters where queries automatically inject the organizationId based on the user's position in the tree.
- Custom UI: Override the Dashboard page or simply add custom Dashboard widgets in the src/apps folder to show different metrics for Dealers vs. Distributors.
- Technical Edge: > "Each tenant owns a tree of organizations... queries, CRUD factories, and generated pages automatically filter to the active organization branch." (Source: Open Mercato Manifest)
- Business Outcome: Deploy complex, multi-layered data isolation that is mathematically guaranteed by the framework, not "if-else" statements in your code.