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.
- 01Full‑stack modules (UI + API + schema)
- 02Clear extension points
- 03Deployment simplicity with strict boundaries
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."
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."
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.
- Row-Level Scoping: Every database query is automatically piped through a global filter that injects tenantId and organizationId, preventing data leaks between customers.
"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."
The stack
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."
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."
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."
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."
Business Outcome
Deploy complex, multi-layered data isolation that is mathematically guaranteed by the framework, not "if-else" statements in your code.