# Architecture — the Modular Monolith behind Open Mercato Source: https://www.openmercato.com/architecture # 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." 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. - 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." Source: OM - Architecture Webinar ## 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." 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. ## Software is about to be built completely differently.