Open Mercato

Open Mercato is a new‑era, AI‑supportive platform for shipping enterprise‑grade CRMs, ERPs, and commerce backends. It’s modular, extensible, and designed so teams can mix their own modules, entities, and workflows while keeping the guardrails of a production-ready stack.

Start with 80% done.

Buy vs. build? Now, you can have best of both. Use Open Mercato enterprise ready business features like CRM, Sales, OMS, Encryption and build the remaining 20% that really makes the difference for your business.

Core Use Cases

• 💼 CRM – model customers, opportunities, and bespoke workflows with infinitely flexible data definitions.
• 🏭 ERP – manage orders, production, and service delivery while tailoring modules to match your operational reality.
• 🛒 Commerce – launch CPQ flows, B2B ordering portals, or full commerce backends with reusable modules.
• 🤝 Self-service system – spin up customer or partner portals with configurable forms, guided flows, and granular permissions.
• 🔄 Workflows – orchestrate custom data lifecycles and document workflows per tenant or team.
• 🧵 Production – coordinate production management with modular entities, automation hooks, and reporting.
• 🌐 Headless/API platform – expose rich, well-typed APIs for mobile and web apps using the same extensible data model.

Highlights

• 🧩 Modular architecture – drop in your own modules, pages, APIs, and entities with auto-discovery and overlay overrides.
• 🧬 Custom entities & dynamic forms – declare fields, validators, and UI widgets per module and manage them live from the admin.
• 🏢 Multi-tenant by default – SaaS-ready tenancy with strict organization/tenant scoping for every entity and API.
• 🏛️ Multi-hierarchical organizations – built-in organization trees with role- and user-level visibility controls.
• 🛡️ Feature-based RBAC – combine per-role and per-user feature flags with organization scoping to gate any page or API.
• ⚡ Data indexing & caching – hybrid JSONB indexing and smart caching for blazing-fast queries across base and custom fields.
• 🔔 Event subscribers & workflows – publish domain events and process them via persistent subscribers (local or Redis).
• ✅ Growing test coverage – expanding unit and integration tests ensure modules stay reliable as you extend them.
• 🧠 AI-supportive foundation – structured for assistive workflows, automation, and conversational interfaces.
• ⚙️ Modern stack – Next.js App Router, TypeScript, zod, Awilix DI, MikroORM, and bcryptjs out of the box.

Screenshots

Order Shipments	Organizations	Users
Roles & ACL	Custom Fields	Custom Entity Records
Add New Customer	Deals Pipeline	Customer Notes
Sales Pipeline	Order Shipments	Order Totals
Catalog Products	Sales Channels	Channel Offers
Home overview with enabled modules list

Architecture Overview

• 🧩 Modules: Each feature lives under src/modules/<module> with auto‑discovered frontend/backend pages, APIs, CLI, i18n, and DB entities.
• 🗃️ Database: MikroORM with per‑module entities and migrations; no global schema. Migrations are generated and applied per module.
• 🧰 Dependency Injection: Awilix container constructed per request. Modules can register and override services/components via di.ts.
• 🏢 Multi‑tenant: Core directory module defines tenants and organizations. Most entities carry tenant_id + organization_id.
• 🔐 Security: RBAC roles, zod validation, bcryptjs hashing, JWT sessions, role‑based access in routes and APIs.

Read more on the Open Mercato Architecture

AI Assistant

Open Mercato includes a built-in AI Assistant that can discover and interact with your data model and APIs. The assistant uses MCP (Model Context Protocol) to expose tools for schema discovery and API execution.

Chat Interface	Settings	MCP Tools

Key capabilities:

• 🔍 Schema Discovery – Query database entity schemas including fields, types, and relationships
• 🔗 API Discovery – Search for API endpoints using natural language queries
• ⚡ API Execution – Execute API calls with automatic tenant context and authentication
• 🧠 Hybrid Search – Uses Meilisearch for fast fulltext + vector search across schemas and endpoints

MCP Tools:

Tool	Purpose
discover_schema	Search entity schemas by name or keyword
find_api	Find API endpoints by natural language query
call_api	Execute API calls with tenant context
context_whoami	Get current authentication context

Integration modes:

• Development (yarn mcp:dev) – For Claude Code and local development with API key auth
• Production (yarn mcp:serve) – For web AI chat with session tokens

See the AI Assistant specification for detailed documentation on entity extraction, OpenAPI integration, and search indexing.

Data Encryption

Open Mercato ships with tenant-scoped, field-level data encryption so PII and sensitive business data stay protected while you keep the flexibility of custom entities and fields. Encryption maps live in the admin UI/database, letting you pick which system and custom columns are encrypted; MikroORM hooks automatically encrypt on write and decrypt on read while keeping deterministic hashes (e.g., email_hash) for lookups.

Architecture in two lines: Vault/KMS (or a derived-key fallback) issues per-tenant DEKs and caches them so performance stays snappy; AES-GCM wrappers sit in the ORM lifecycle, storing ciphertext at rest while CRUD and APIs keep working with plaintext. Read the docs to dive deeper: docs.openmercato.com/user-guide/encryption.

Migration Guide

We have migrated Open Mercato to a monorepo structure. If you're upgrading from a previous version, please note the following changes:

File Structure

The codebase is now organized into:

• packages/ - Shared libraries and modules (@open-mercato/core, @open-mercato/ui, @open-mercato/shared, @open-mercato/cli, @open-mercato/cache, @open-mercato/events, @open-mercato/queue, @open-mercato/content, @open-mercato/onboarding, @open-mercato/search, @open-mercato/enterprise)
• apps/ - Applications (main app in apps/mercato, docs in apps/docs)

Important note on storage: The storage folder has been moved to the apps/mercato folder as well. If you instance has got any attachments uploaded, please make sure you run:

mv storage apps/mercato/storage

... from the root Open Mercato folder.

Import Aliases

Import aliases have changed from path-based to package-based imports:

• Before: @/lib/..., @/components/..., @/modules/...
• After: @open-mercato/shared/lib/..., @open-mercato/ui/components/..., @open-mercato/core/modules/..., etc.

Environment Variables

The .env file now must live in apps/mercato instead of the project root. The fastest way to start is to copy the example file:

cp apps/mercato/.env.example apps/mercato/.env

At minimum, set DATABASE_URL, JWT_SECRET, and REDIS_URL (or EVENTS_REDIS_URL) before bootstrapping.

Package Manager

Yarn 4 is now required. Ensure you have Yarn 4+ installed before proceeding.

Getting Started

This is a quickest way to get Open Mercato up and running on your localhost / server - ready for testing / demoing or for Core development!

Installation update

Node.js 24.x is required

# macOS (Homebrew)
brew install node@24

# Windows (Chocolatey)
choco install nodejs --version=24.x

# Or use nvm (any platform)
nvm install 24
nvm use 24

Windows: Use Docker Setup for native setup.

Quick Start (Monorepo)

Prerequisites: Yarn 4+

Quick single-line starter (ephemeral dev on a free port):

yarn dev:ephemeral

git clone https://github.com/open-mercato/open-mercato.git
cd open-mercato
git checkout develop
yarn install

cp apps/mercato/.env.example apps/mercato/.env # EDIT this file to set up your specific files
#At minimum, set `DATABASE_URL`, `JWT_SECRET`, and `REDIS_URL` (or `EVENTS_REDIS_URL`) before bootstrapping.

yarn generate
yarn initialize # or yarn reinstall
yarn dev

For a fresh greenfield boot (build packages, generate registries, reinstall modules, then start dev), run:

yarn dev:greenfield

For a worktree-friendly dev runtime with a dedicated ephemeral PostgreSQL database and an automatically selected free app port (with Node 24 check, dependency install, package build, .env bootstrap, generator prep, browser auto-open, and instance registry in .ai/dev-ephemeral-envs.json), run:

yarn dev:ephemeral

Navigate to http://localhost:3000/backend and sign in with the default credentials printed by yarn initialize.

Full installation guide (including prerequisites, Docker setup, and cloud deployment): docs.openmercato.com/installation/setup

Docker Setup

Open Mercato offers two Docker Compose configurations — one for development (with hot reload) and one for production. Both run the full stack (app + PostgreSQL + Redis + Meilisearch) in containers. The dev mode is the recommended setup for Windows users.

Dev mode (hot reload)

Run the entire stack with source code mounted from the host. File changes trigger automatic rebuilds — no local Node.js or Yarn required.

git clone https://github.com/open-mercato/open-mercato.git
cd open-mercato
git checkout develop
docker compose -f docker-compose.fullapp.dev.yml up --build

Windows users: Ensure WSL 2 backend is enabled in Docker Desktop and clone with git config --global core.autocrlf input to avoid line-ending issues.

Production mode

docker compose -f docker-compose.fullapp.yml up --build

Common operations:

• Start: docker compose -f docker-compose.fullapp.yml up -d
• Logs: docker compose -f docker-compose.fullapp.yml logs -f app
• Stop: docker compose -f docker-compose.fullapp.yml down
• Rebuild: docker compose -f docker-compose.fullapp.yml up --build

Navigate to http://localhost:3000/backend and sign in with the default credentials (admin@example.com).

Docker Environment Variables

Before starting, you may want to configure the following environment variables. Create a .env file in the project root or export them in your shell:

Variable	Required	Default	Description
JWT_SECRET	For production	JWT	Secret key for JWT token signing. Use a strong, unique value in production.
POSTGRES_PASSWORD	For production	postgres	PostgreSQL database password. Use a strong password in production.
POSTGRES_USER	No	postgres	PostgreSQL database user
POSTGRES_DB	No	open-mercato	PostgreSQL database name
POSTGRES_PORT	No	5432	PostgreSQL exposed port
REDIS_PORT	No	6379	Redis exposed port
MEILISEARCH_MASTER_KEY	For production	meilisearch-dev-key	Meilisearch API key. Use a strong key in production.
MEILISEARCH_PORT	No	7700	Meilisearch exposed port
OPENAI_API_KEY	No	-	OpenAI API key (enables AI features)
ANTHROPIC_API_KEY	No	-	Anthropic API key (for opencode service)
OPENCODE_PORT	No	4096	Opencode service exposed port

Example .env file for production:

JWT_SECRET=your-strong-secret-key-here
POSTGRES_PASSWORD=your-strong-db-password
MEILISEARCH_MASTER_KEY=your-strong-meilisearch-key
OPENAI_API_KEY=sk-...  # Optional, for AI features

VPS Deployment

For production deployments, ensure strong JWT_SECRET, secure database credentials, and consider managed database services. See the full Docker deployment guide for detailed configuration and production tips.

Standalone App & Customization

The recommended way to build on Open Mercato without modifying the core is to create a standalone app. This gives you a self-contained project that pulls Open Mercato packages from npm — your own modules, overrides, and customizations live in your repo while core stays untouched and upgradeable.

Create a standalone app

npx create-mercato-app my-store
cd my-store
cp .env.example .env   # configure DATABASE_URL, JWT_SECRET, REDIS_URL
docker compose up -d   # start PostgreSQL, Redis, Meilisearch
yarn install
yarn initialize
yarn dev

Navigate to http://localhost:3000/backend and sign in with the credentials printed by yarn initialize.

Add custom modules

Drop your own modules into src/modules/ and register them in src/modules.ts with from: '@app':

export const enabledModules: ModuleEntry[] = [
  // ... core modules
  { id: 'inventory', from: '@app' },
]

Run yarn generate and yarn dev — your module's pages, APIs, and entities are auto-discovered.

Extend backend navigation with menu injection (SPEC-041 A/B)

Open Mercato now supports declarative menu injection for backend chrome surfaces without touching core files.

1. Create a headless widget in your module:

// src/modules/example/widgets/injection/example-menus/widget.ts
import { InjectionPosition } from '@open-mercato/shared/modules/widgets/injection-position'
import type { InjectionMenuItemWidget } from '@open-mercato/shared/modules/widgets/injection'

export default {
  metadata: { id: 'example.injection.example-menus', features: ['example.view'] },
  menuItems: [
    {
      id: 'example-todos-shortcut',
      label: 'example.menu.todosShortcut',
      href: '/backend/example/todos',
      groupId: 'example.nav.group',
      groupLabelKey: 'example.nav.group',
      placement: { position: InjectionPosition.Last },
    },
  ],
} satisfies InjectionMenuItemWidget

2. Map it in widgets/injection-table.ts:

export const injectionTable = {
  'menu:sidebar:main': { widgetId: 'example.injection.example-menus', priority: 50 },
  'menu:topbar:actions': { widgetId: 'example.injection.example-menus', priority: 50 },
  'menu:topbar:profile-dropdown': { widgetId: 'example.injection.example-menus', priority: 50 },
}

3. Run yarn generate.

Available surfaces: menu:sidebar:main, menu:sidebar:settings, menu:sidebar:profile, menu:topbar:actions, menu:topbar:profile-dropdown.

Eject core modules for deep customization

When you need to change the internals of a core module (entities, business logic, UI), eject it. The mercato eject command copies the module source into your src/modules/ directory and switches it to local, so you can modify it freely while all other modules keep receiving package updates.

# See which modules support ejection
yarn mercato eject --list

# Eject a module (e.g., currencies)
yarn mercato eject currencies
yarn mercato generate all
yarn dev

Currently ejectable: catalog, currencies, customers, perspectives, planner, resources, sales, staff, workflows.

Full guide: docs.openmercato.com/customization/standalone-app · CLI reference: docs.openmercato.com/cli/eject

Live demo

Documentation

Browse the full documentation at docs.openmercato.com.

• Introduction
• Installation
• User Guide
• Tutorials
• Customization
• Architecture
• Framework
• API Reference
• CLI Reference
• Appendix

Spec Driven Development

Open Mercato follows a spec-first development approach. Before implementing new features or making significant changes, we document the design in the .ai/specs/ folder.

Why Specs?

• Clarity: Specs ensure everyone understands the feature before coding starts
• Consistency: Design decisions are documented and can be referenced by humans and AI agents
• Traceability: Each spec maintains a changelog tracking the evolution of the feature

How It Works

1. Before coding: Check if a spec exists in .ai/specs/ (named SPEC-###-YYYY-MM-DD-title.md)
2. New features: Create or update the spec with your design before implementation
3. After changes: Update the spec's changelog with a dated summary

Naming convention: Specs use the format SPEC-{number}-{date}-{title}.md (e.g., SPEC-007-2026-01-26-sidebar-reorganization.md)

See .ai/specs/README.md for the full specification directory and .ai/specs/AGENTS.md for detailed guidelines on maintaining specs.

Join us on Discord

Connect with the team and other builders in our Discord community: https://discord.gg/f4qwPtJ3qA.

Contributing

We welcome contributions of all sizes—from fixes and docs updates to new modules. Start by reading CONTRIBUTING.md for branching conventions (main, develop, feat/<feature>), release flow, and the full PR checklist. Then check the open issues or propose an idea in a discussion, and:

1. Fork the repository and create a branch that reflects your change.
2. Install dependencies with yarn install and bootstrap via yarn mercato init (add --no-examples to skip demo CRM content; --stresstest for thousands of synthetic contacts, companies, deals, and timeline interactions; or --stresstest --lite for high-volume contacts without the heavier extras).
3. Develop and validate your changes (yarn lint, yarn test, or the relevant module scripts).
4. Open a pull request referencing any related issues and outlining the testing you performed.

Refer to AGENTS.md for deeper guidance on architecture and conventions when extending modules.

Open Mercato is proudly supported by Catch The Tornado.

CLI Commands

Open Mercato let the module developers to expose the custom CLI commands for variouse maintenance tasks. Read more on the CLI documentation

Considering a project on Open Mercato?

If you're planning to build on Open Mercato, don’t go it alone.

Certified Partner Agencies

Reach out to us - we will connect you with one of our Certified Partner Agencies. Our Partnership Program certifies software consultancies that actively use and contribute to Open Mercato.

Our mission is simple: ensure every Open Mercato deployment is successful, secure, and scalable.

License

• MIT — see LICENSE for details. Enterprise licensing details are documented in packages/enterprise/README.md.

Enterprise Edition

Open Mercato Core is and always will be MIT Licensed, fully Open Source.

Open Mercato Enterprise Subscription

The Open Mercato Enterprise Subscription helps ensure your deployment is secure, scalable, and production-ready without surprises before go-live.

It combines certification, expert reviews, and ongoing advisory support for teams building serious systems on Open Mercato.

What’s included:

• Architecture & Production Readiness
• Pre-deployment architecture audit
• Production approval before go-live
• Hosting and deployment best practices
• Security & Quality (monthly reviews)
• Customer Success Manager (pre-go-live)
• Priority technical support channel
• Platform Continuity - access to security patches and new features

Contact us to get support for your implementation: info@openmercato.com

Enterprise features are delivered under the @open-mercato/enterprise package (/packages/enterprise) and are not part of the open source license scope.