How Open Mercato Works

Open Mercato runs as a Next.js application. Business modules share services for access control, data and background work. Start with that structure, then follow a read, a write or an integration through the diagram below.

On this page

What runs together?

Your application selects the business modules it needs. Generated registries connect their pages, API routes and services to the application. A module is a unit of source code; it does not automatically become a separately deployed service.

Architecture in practiceOne application, modules inside it, services around it

Browser / API clientHTTPS

request

Your Next.js application

CRM

Sales

Your module

Shared: access control · commands · data queries · events

↓ read / write↓ enqueue work

PostgreSQLBusiness records

Queue + workerFor configured background work

Code and documentation

generators/module-registry.ts

Follow an example

From user action to result

Choose a scenario, then a step. See which component does the work, what it receives and what it passes on.

Example

You open a customer record

Follow a read through a module API. The selected organization determines which records the request may access.

Step 1 / 4

Open the record

The page requests one customer using its identifier. It sends the signed-in session with the request.

Receives: customerId: "42"
Passes on: Request to the module API

ResultThe browser displays the customer data returned by the API.

What can go wrong?An unknown or inaccessible customer must not reveal data from another organization. Enforce this in the route and query scope.

Explore this mechanism →

Enable JavaScript to step through each example, or read the complete scenarios below.

You open a customer record

Open the record. The page requests one customer using its identifier. It sends the signed-in session with the request.
Check access. The route checks authentication and required permissions, then determines the tenant and organization scope for the read.
Find the record. The module reads through its query path. Filters must include the applicable scope; the customer identifier alone does not establish access.
Return the view. The API formats the response. Configured response enrichers may add fields before the page renders the result.

Read the guide

You change a customer address

Submit the form. The form sends the changed fields and record identifier. Client validation gives immediate feedback, but the server must validate again.
Validate the write. The route verifies data and access. Registered mutation guards can stop a write when a business rule fails.
Perform the change. The registered command runs its write logic. Logging and undo depend on the hooks implemented by that command.
Return the result. The write persists data and may emit declared events or update indexes through its configured helpers. The API then returns a result to the form.

Read the guide

A lost deal triggers a notification

Change the deal. The business operation marks the deal as lost. This is the action the user requested.
Publish the event. The event names what happened and carries the data the notification handler needs. Other modules subscribe by event name.
Dispatch the subscriber. The registered subscriber declares this event and persistent: true. Queue and emission settings determine background delivery.
Create the notification. The handler delegates to deliverDealClosureNotification. The business event and its notification remain separate pieces of code.

Read the guide

Add a panel to a customer page

Build the panel. Create the UI in your module. For example, a panel may show service cases associated with the displayed customer.
Choose its location. Map the widget to an injection slot provided by the host page. Use an existing slot identifier from that page.
Register the module. Enable your module and regenerate the registries. The application can then discover the widget and its mapping.
Render in context. The page renders the widget in its slot. The panel uses the supplied context and an authorized API to load its own records.

Read the guide

Send an order to a warehouse system

Prepare the job. Choose which order transition should trigger the transfer. Gather the order identifier and the correct tenant and organization context.
Run outside the request. A worker picks up the job. It can retry a temporary failure without making the user keep the form open.
Translate and send. Resolve credentials on the server, convert fields and call the external API. A provider package or your own implementation owns this logic.
Record the result. Store the destination identifier and processing status. Keep enough information to reconcile records and resume failures.

Read the guide

Where to look when something goes wrong

Symptom	Start here
Your page does not appear	Module registration, generated routes, then the permission required by the page.
The form sends data but the save is rejected	API response, input schema and access scope; then the command and its guards.
The save succeeds but an external system is unchanged	Event emission, subscriber registration, queued job and worker error logs.

Code and documentation

generators/module-registry.ts · crud/factory.ts · src/factory.ts

Example: saving a customer

A customer form sends a request to an API route. A route built with makeCrudRoute can validate the input, check access and call a registered command. The command performs the change. DataEngine can coordinate persistence, declared events and index updates.

A direct ORM write can skip command logging, guards or event handling that the normal route uses. When an import updates the database but the screen or search results stay unchanged, compare the import path with the route used by the form.

Code and documentation

crud/factory.ts · commands/command-bus.ts · data/engine.ts

What do you deploy?

Plan the application and database first. Add workers, cache, search and file storage according to the features and strategies you enable. Record which service owns each piece of data and how it will be restored after a failure.

Code and documentation

src/service.ts · src/service.ts · src/factory.ts

Sources

Open Mercato source used in these explanations