{"id":35145255,"url":"https://github.com/open-mercato/open-mercato","last_synced_at":"2026-03-13T13:04:00.511Z","repository":{"id":314450779,"uuid":"1054179260","full_name":"open-mercato/open-mercato","owner":"open-mercato","description":" AI‑supportive CRM / ERP foundation framework — built to power R\u0026D, new processes, operations, and growth. It’s modular, extensible, and designed for teams that want strong defaults with room to customize everything. Better than Django, Retool and other alternatives - and Enterprise Grade!","archived":false,"fork":false,"pushed_at":"2026-03-07T22:12:11.000Z","size":81531,"stargazers_count":1061,"open_issues_count":209,"forks_count":173,"subscribers_count":11,"default_branch":"main","last_synced_at":"2026-03-08T01:51:42.320Z","etag":null,"topics":["crm","crm-platform","erp","typescript"],"latest_commit_sha":null,"homepage":"https://docs.openmercato.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/open-mercato.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-10T13:27:45.000Z","updated_at":"2026-03-07T19:52:33.000Z","dependencies_parsed_at":"2025-09-12T15:57:26.715Z","dependency_job_id":"a1eee8f8-80b4-4d1d-9986-0f571ebb2848","html_url":"https://github.com/open-mercato/open-mercato","commit_stats":null,"previous_names":["pkarw/open-mercato","open-mercato/open-mercato"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/open-mercato/open-mercato","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-mercato%2Fopen-mercato","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-mercato%2Fopen-mercato/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-mercato%2Fopen-mercato/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-mercato%2Fopen-mercato/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/open-mercato","download_url":"https://codeload.github.com/open-mercato/open-mercato/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-mercato%2Fopen-mercato/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30292186,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T11:12:22.024Z","status":"ssl_error","status_checked_at":"2026-03-09T11:10:54.577Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crm","crm-platform","erp","typescript"],"created_at":"2025-12-28T13:42:10.392Z","updated_at":"2026-03-13T13:04:00.502Z","avatar_url":"https://github.com/open-mercato.png","language":"TypeScript","funding_links":[],"categories":["Others","Repos","🤖 AI \u0026 Machine Learning"],"sub_categories":["Usage"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./apps/mercato/public/open-mercato.svg\" alt=\"Open Mercato logo\" width=\"120\" /\u003e\n\u003c/p\u003e\n\n# Open Mercato\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Docs](https://img.shields.io/badge/docs-openmercato.com-1F7AE0.svg)](https://docs.openmercato.com/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-ff69b4.svg)](https://github.com/open-mercato/open-mercato/issues)\n[![Built with Next.js](https://img.shields.io/badge/Built%20with-Next.js-black?logo=next.js)](https://nextjs.org/)\n\nOpen 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.\n\n## Start with 80% done.\n\n**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\u0026percnt;** that really makes the difference for your business.\n\n[![Watch: What “Start with 80% done” means](https://img.youtube.com/vi/53jsDjAXXhQ/maxresdefault.jpg)](https://www.youtube.com/watch?v=53jsDjAXXhQ)\n\n\n## Core Use Cases\n\n- 💼 **CRM** – model customers, opportunities, and bespoke workflows with infinitely flexible data definitions.\n- 🏭 **ERP** – manage orders, production, and service delivery while tailoring modules to match your operational reality.\n- 🛒 **Commerce** – launch CPQ flows, B2B ordering portals, or full commerce backends with reusable modules.\n- 🤝 **Self-service system** – spin up customer or partner portals with configurable forms, guided flows, and granular permissions.\n- 🔄 **Workflows** – orchestrate custom data lifecycles and document workflows per tenant or team.\n- 🧵 **Production** – coordinate production management with modular entities, automation hooks, and reporting.\n- 🌐 **Headless/API platform** – expose rich, well-typed APIs for mobile and web apps using the same extensible data model.\n\n## Highlights\n\n- 🧩 **Modular architecture** – drop in your own modules, pages, APIs, and entities with auto-discovery and overlay overrides.\n- 🧬 **Custom entities \u0026 dynamic forms** – declare fields, validators, and UI widgets per module and manage them live from the admin.\n- 🏢 **Multi-tenant by default** – SaaS-ready tenancy with strict organization/tenant scoping for every entity and API.\n- 🏛️ **Multi-hierarchical organizations** – built-in organization trees with role- and user-level visibility controls.\n- 🛡️ **Feature-based RBAC** – combine per-role and per-user feature flags with organization scoping to gate any page or API.\n- ⚡ **Data indexing \u0026 caching** – hybrid JSONB indexing and smart caching for blazing-fast queries across base and custom fields.\n- 🔔 **Event subscribers \u0026 workflows** – publish domain events and process them via persistent subscribers (local or Redis).\n- ✅ **Growing test coverage** – expanding unit and integration tests ensure modules stay reliable as you extend them.\n- 🧠 **AI-supportive foundation** – structured for assistive workflows, automation, and conversational interfaces.\n- ⚙️ **Modern stack** – Next.js App Router, TypeScript, zod, Awilix DI, MikroORM, and bcryptjs out of the box.\n\n\n## Screenshots\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"./apps/docs/static/screenshots/open-mercato-orders-order-shipments.png\"\u003e\u003cimg src=\"./apps/docs/static/screenshots/open-mercato-orders-order-shipments.png\" alt=\"Order shipments timeline\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"./apps/docs/static/screenshots/open-mercato-edit-organization.png\"\u003e\u003cimg src=\"./apps/docs/static/screenshots/open-mercato-edit-organization.png\" alt=\"Editing an organization\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"./apps/docs/static/screenshots/open-mercato-users-management.png\"\u003e\u003cimg src=\"./apps/docs/static/screenshots/open-mercato-users-management.png\" alt=\"Users management view\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd style=\"text-align:center;\"\u003eOrder Shipments\u003c/td\u003e\n    \u003ctd style=\"text-align:center;\"\u003eOrganizations\u003c/td\u003e\n    \u003ctd style=\"text-align:center;\"\u003eUsers\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"./apps/docs/static/screenshots/open-mercato-managing-roles.png\"\u003e\u003cimg src=\"./apps/docs/static/screenshots/open-mercato-managing-roles.png\" alt=\"Managing roles and permissions\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"./apps/docs/static/screenshots/open-mercato-define-custom-fields.png\"\u003e\u003cimg src=\"./apps/docs/static/screenshots/open-mercato-define-custom-fields.png\" alt=\"Defining custom fields\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"./apps/docs/static/screenshots/open-mercato-custom-entity-records.png\"\u003e\u003cimg src=\"./apps/docs/static/screenshots/open-mercato-custom-entity-records.png\" alt=\"Managing custom entity records\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd style=\"text-align:center;\"\u003eRoles \u0026amp; ACL\u003c/td\u003e\n    \u003ctd style=\"text-align:center;\"\u003eCustom Fields\u003c/td\u003e\n    \u003ctd style=\"text-align:center;\"\u003eCustom Entity Records\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"./apps/docs/static/screenshots/open-mercato-people-add-new.png\"\u003e\u003cimg src=\"./apps/docs/static/screenshots/open-mercato-people-add-new.png\" alt=\"Add new customer form\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"./apps/docs/static/screenshots/open-mercato-deals-listing.png\"\u003e\u003cimg src=\"./apps/docs/static/screenshots/open-mercato-deals-listing.png\" alt=\"Deals pipeline board\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"./apps/docs/static/screenshots/open-mercato-people-notes.png\"\u003e\u003cimg src=\"./apps/docs/static/screenshots/open-mercato-people-notes.png\" alt=\"Customer notes timeline\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd style=\"text-align:center;\"\u003eAdd New Customer\u003c/td\u003e\n    \u003ctd style=\"text-align:center;\"\u003eDeals Pipeline\u003c/td\u003e\n    \u003ctd style=\"text-align:center;\"\u003eCustomer Notes\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"./apps/docs/static/screenshots/open-mercato-sales-pipeline.png\"\u003e\u003cimg src=\"./apps/docs/static/screenshots/open-mercato-sales-pipeline.png\" alt=\"Sales pipeline board view\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"./apps/docs/static/screenshots/open-mercato-orders-order-shipments.png\"\u003e\u003cimg src=\"./apps/docs/static/screenshots/open-mercato-orders-order-shipments.png\" alt=\"Order shipments timeline\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"./apps/docs/static/screenshots/open-mercato-orders-order-totals.png\"\u003e\u003cimg src=\"./apps/docs/static/screenshots/open-mercato-orders-order-totals.png\" alt=\"Order totals breakdown\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd style=\"text-align:center;\"\u003eSales Pipeline\u003c/td\u003e\n    \u003ctd style=\"text-align:center;\"\u003eOrder Shipments\u003c/td\u003e\n    \u003ctd style=\"text-align:center;\"\u003eOrder Totals\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"./apps/docs/static/screenshots/open-mercato-catalog-products.png\"\u003e\u003cimg src=\"./apps/docs/static/screenshots/open-mercato-catalog-products.png\" alt=\"Catalog products list\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"./apps/docs/static/screenshots/open-mercato-sales-channels.png\"\u003e\u003cimg src=\"./apps/docs/static/screenshots/open-mercato-sales-channels.png\" alt=\"Sales channels overview\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"./apps/docs/static/screenshots/open-mercato-all-sales-channels-offers.png\"\u003e\u003cimg src=\"./apps/docs/static/screenshots/open-mercato-all-sales-channels-offers.png\" alt=\"Sales channel offers listing\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd style=\"text-align:center;\"\u003eCatalog Products\u003c/td\u003e\n    \u003ctd style=\"text-align:center;\"\u003eSales Channels\u003c/td\u003e\n    \u003ctd style=\"text-align:center;\"\u003eChannel Offers\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd colspan=\"3\" style=\"text-align:center;\" halign=\"center\"\u003e\n      \u003ca href=\"./apps/docs/static/screenshots/open-mercato-homepage.png\"\u003e\u003cimg src=\"./apps/docs/static/screenshots/open-mercato-homepage.png\" alt=\"Home page showing enabled modules\" width=\"520\"/\u003e\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd colspan=\"3\" style=\"text-align:center;\"\u003eHome overview with enabled modules list\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\n## Architecture Overview\n\n- 🧩 Modules: Each feature lives under `src/modules/\u003cmodule\u003e` with auto‑discovered frontend/backend pages, APIs, CLI, i18n, and DB entities.\n- 🗃️ Database: MikroORM with per‑module entities and migrations; no global schema. Migrations are generated and applied per module.\n- 🧰 Dependency Injection: Awilix container constructed per request. Modules can register and override services/components via `di.ts`.\n- 🏢 Multi‑tenant: Core `directory` module defines `tenants` and `organizations`. Most entities carry `tenant_id` + `organization_id`.\n- 🔐 Security: RBAC roles, zod validation, bcryptjs hashing, JWT sessions, role‑based access in routes and APIs.\n\nRead more on the [Open Mercato Architecture](https://docs.openmercato.com/architecture/system-overview)\n\n## AI Assistant\n\nOpen 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.\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"apps/docs/static/screenshots/open-mercato-ai-assistant-chat.png\"\u003e\u003cimg src=\"apps/docs/static/screenshots/open-mercato-ai-assistant-chat.png\" alt=\"AI Assistant chat interface\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"apps/docs/static/screenshots/open-mercato-ai-assistant-settings.png\"\u003e\u003cimg src=\"apps/docs/static/screenshots/open-mercato-ai-assistant-settings.png\" alt=\"AI Assistant settings\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ca href=\"apps/docs/static/screenshots/open-mercato-ai-assistant-mcp.png\"\u003e\u003cimg src=\"apps/docs/static/screenshots/open-mercato-ai-assistant-mcp.png\" alt=\"AI Assistant MCP tools\" width=\"260\"/\u003e\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd style=\"text-align:center;\"\u003eChat Interface\u003c/td\u003e\n    \u003ctd style=\"text-align:center;\"\u003eSettings\u003c/td\u003e\n    \u003ctd style=\"text-align:center;\"\u003eMCP Tools\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n**Key capabilities:**\n- 🔍 **Schema Discovery** – Query database entity schemas including fields, types, and relationships\n- 🔗 **API Discovery** – Search for API endpoints using natural language queries\n- ⚡ **API Execution** – Execute API calls with automatic tenant context and authentication\n- 🧠 **Hybrid Search** – Uses Meilisearch for fast fulltext + vector search across schemas and endpoints\n\n**MCP Tools:**\n| Tool | Purpose |\n|------|---------|\n| `discover_schema` | Search entity schemas by name or keyword |\n| `find_api` | Find API endpoints by natural language query |\n| `call_api` | Execute API calls with tenant context |\n| `context_whoami` | Get current authentication context |\n\n**Integration modes:**\n- **Development** (`yarn mcp:dev`) – For Claude Code and local development with API key auth\n- **Production** (`yarn mcp:serve`) – For web AI chat with session tokens\n\nSee the [AI Assistant specification](.ai/specs/SPEC-012-2026-01-27-ai-assistant-schema-discovery.md) for detailed documentation on entity extraction, OpenAPI integration, and search indexing.\n\n## Data Encryption\n\nOpen 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.\n\nArchitecture 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](https://docs.openmercato.com/user-guide/encryption).\n\n\n## Migration Guide\n\nWe have migrated Open Mercato to a monorepo structure. If you're upgrading from a previous version, please note the following changes:\n\n### File Structure\n\nThe codebase is now organized into:\n- `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`)\n- `apps/` - Applications (main app in `apps/mercato`, docs in `apps/docs`)\n\n**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:\n\n```bash\nmv storage apps/mercato/storage\n```\n\n... from the root Open Mercato folder.\n\n### Import Aliases\n\nImport aliases have changed from path-based to package-based imports:\n- **Before:** `@/lib/...`, `@/components/...`, `@/modules/...`\n- **After:** `@open-mercato/shared/lib/...`, `@open-mercato/ui/components/...`, `@open-mercato/core/modules/...`, etc.\n\n### Environment Variables\n\nThe `.env` file now must live in `apps/mercato` instead of the project root.\nThe fastest way to start is to copy the example file:\n\n```bash\ncp apps/mercato/.env.example apps/mercato/.env\n```\nAt minimum, set `DATABASE_URL`, `JWT_SECRET`, and `REDIS_URL` (or `EVENTS_REDIS_URL`) before bootstrapping.\n\n### Package Manager\n\nYarn 4 is now required. Ensure you have Yarn 4+ installed before proceeding.\n\n## Getting Started\n\n\nThis is a quickest way to get Open Mercato up and running on your localhost / server - ready for testing / demoing or for `Core development`!\n\n[![Watch on YouTube](https://img.youtube.com/vi/-ba8Bmc56EQ/maxresdefault.jpg)](https://youtu.be/-ba8Bmc56EQ)\n\n### Installation update\n**Node.js 24.x is required**\n  ```bash\n  # macOS (Homebrew)\n  brew install node@24\n\n  # Windows (Chocolatey)\n  choco install nodejs --version=24.x\n\n  # Or use nvm (any platform)\n  nvm install 24\n  nvm use 24\n  ```\n  \n**Windows:** Use [Docker Setup](#docker-setup) for native setup.\n\n### Quick Start (Monorepo)\n\n**Prerequisites:** Yarn 4+\n\nQuick single-line starter (ephemeral dev on a free port):\n\n```bash\nyarn dev:ephemeral\n```\n\n```bash\ngit clone https://github.com/open-mercato/open-mercato.git\ncd open-mercato\ngit checkout develop\nyarn install\n\ncp apps/mercato/.env.example apps/mercato/.env # EDIT this file to set up your specific files\n#At minimum, set `DATABASE_URL`, `JWT_SECRET`, and `REDIS_URL` (or `EVENTS_REDIS_URL`) before bootstrapping.\n\nyarn generate\nyarn initialize # or yarn reinstall\nyarn dev\n```\n\nAfter upgrading to a newer version, apply any new module migrations:\n\n```bash\nyarn db:migrate\n```\n\nNote: `yarn initialize` seeds demo data and may abort if users already exist. For upgrades on an existing database, use `yarn db:migrate` instead.\n\nFor a fresh greenfield boot (build packages, generate registries, reinstall modules, then start dev), run:\n\n```bash\nyarn dev:greenfield\n```\n\nFor 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:\n\n```bash\nyarn dev:ephemeral\n```\n\nNavigate to `http://localhost:3000/backend` and sign in with the default credentials printed by `yarn initialize`.\n\nFull installation guide (including prerequisites, Docker setup, and cloud deployment): [docs.openmercato.com/installation/setup](https://docs.openmercato.com/installation/setup)\n\n## Docker Setup\n\nOpen 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.\n\n### Dev mode (hot reload)\n\nRun the entire stack with source code mounted from the host. File changes trigger automatic rebuilds — no local Node.js or Yarn required.\n\n```bash\ngit clone https://github.com/open-mercato/open-mercato.git\ncd open-mercato\ngit checkout develop\ndocker compose -f docker-compose.fullapp.dev.yml up --build\n```\n\n**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.\n\nOnce the dev stack is running, you can use the Docker wrapper scripts from the repo root instead of typing `docker compose exec` manually:\n\n```bash\nyarn docker:build:packages\nyarn docker:generate\nyarn docker:initialize\nyarn docker:initialize -- --reinstall\nyarn docker:db:migrate\nyarn docker:lint\nyarn docker:typecheck\nyarn docker:test\nyarn docker:install-skills\nyarn docker:dev -- --skip-rebuilt\n```\n\n### Production mode\n\n```bash\ndocker compose -f docker-compose.fullapp.yml up --build\n```\n\n**Common operations:**\n\n- Start: `docker compose -f docker-compose.fullapp.yml up -d`\n- Logs: `docker compose -f docker-compose.fullapp.yml logs -f app`\n- Stop: `docker compose -f docker-compose.fullapp.yml down`\n- Rebuild: `docker compose -f docker-compose.fullapp.yml up --build`\n\nFor runtime-oriented tasks on the fullapp stack, use the Docker wrappers as well:\n\n```bash\nyarn docker:db:migrate\nyarn docker:mercato auth:list-users\n```\n\nNavigate to `http://localhost:3000/backend` and sign in with the default credentials (admin@example.com).\n\n### Docker Environment Variables\n\nBefore starting, you may want to configure the following environment variables. Create a `.env` file in the project root or export them in your shell:\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `JWT_SECRET` | For production | `JWT` | Secret key for JWT token signing. **Use a strong, unique value in production.** |\n| `POSTGRES_PASSWORD` | For production | `postgres` | PostgreSQL database password. **Use a strong password in production.** |\n| `POSTGRES_USER` | No | `postgres` | PostgreSQL database user |\n| `POSTGRES_DB` | No | `open-mercato` | PostgreSQL database name |\n| `POSTGRES_PORT` | No | `5432` | PostgreSQL exposed port |\n| `REDIS_PORT` | No | `6379` | Redis exposed port |\n| `MEILISEARCH_MASTER_KEY` | For production | `meilisearch-dev-key` | Meilisearch API key. **Use a strong key in production.** |\n| `MEILISEARCH_PORT` | No | `7700` | Meilisearch exposed port |\n| `OPENAI_API_KEY` | No | - | OpenAI API key (enables AI features) |\n| `ANTHROPIC_API_KEY` | No | - | Anthropic API key (for opencode service) |\n| `OPENCODE_PORT` | No | `4096` | Opencode service exposed port |\n\nExample `.env` file for production:\n\n```bash\nJWT_SECRET=your-strong-secret-key-here\nPOSTGRES_PASSWORD=your-strong-db-password\nMEILISEARCH_MASTER_KEY=your-strong-meilisearch-key\nOPENAI_API_KEY=sk-...  # Optional, for AI features\n```\n\n### Ephemeral Environments\n\nSpin up a self-contained, throwaway environment for quick testing or previewing a branch — no local database, or full dev setup required. Each run starts with a fresh database and is automatically reset on restart.\n\n```bash\ndocker compose -f docker-compose.preview.yaml up --build\n```\n\nNavigate to `http://localhost:5000`.\n\nTo stop the environment:\n\n```bash\ndocker compose -f docker-compose.preview.yaml down\n```\n\n\u003e **Attention:** This type of deployment is ephemeral and intended for testing purposes only. After stopping the containers, all data will be lost. Do not use this setup in production.\n\n\n### Deploy on Railway\n\n[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/TKvo95)\n\nOne-click deployment on [Railway](https://railway.com) with PostgreSQL (pgvector), Redis, and Meilisearch provisioned automatically.\n\n\u003e **Note:** Open Mercato requires at least **2 GB of memory**. The Railway **Hobby plan** (or higher) is required — the free tier is not sufficient.\n\nSee the [Railway deployment guide](https://docs.openmercato.com/installation/railway) for environment variables, first-boot setup, and custom domain configuration.\n\n### VPS Deployment\n\n[![Watch: Deploy Open Mercato on a VPS](https://img.youtube.com/vi/xau17YBP9ek/maxresdefault.jpg)](https://www.youtube.com/watch?v=xau17YBP9ek)\n\nFor production deployments, ensure strong `JWT_SECRET`, secure database credentials, and consider managed database services. See the [full Docker deployment guide](https://docs.openmercato.com/installation/setup#docker-deployment-full-stack) for detailed configuration and production tips.\n\n### Dev Container (VS Code)\n\nThe fastest way to get a fully working dev environment — no local toolchain required.\n\n**Prerequisites**: [Docker Desktop](https://www.docker.com/products/docker-desktop/) (12 GB+ memory in Settings → Resources) + VS Code with the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension.\n\n```bash\ngit clone https://github.com/open-mercato/open-mercato.git\ncode open-mercato\n# VS Code → Command Palette → \"Dev Containers: Reopen in Container\"\n# Wait for setup to complete (~3-5 min on first build), then:\nyarn dev\n```\n\nThe container includes Node.js 24, Yarn 4, PostgreSQL (with pgvector), Redis, Meilisearch, and Claude Code CLI — all pre-configured and ready to use.\n\n- **Customize env vars**: create `apps/mercato/.env.local` (takes priority over `.env`, which is auto-generated)\n- **Claude Code CLI**: run `claude` inside the container and follow the OAuth login flow (works with Max plan subscriptions), or set `export ANTHROPIC_API_KEY=sk-...` in your host shell before opening the container for API key auth\n- **Rebuild**: if you need a fresh start, use Command Palette → \"Dev Containers: Rebuild Container\"\n\n## Standalone App \u0026 Customization\n\nThe **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.\n\n### Create a standalone app\n\n```bash\nnpx create-mercato-app my-store\ncd my-store\ncp .env.example .env   # configure DATABASE_URL, JWT_SECRET, REDIS_URL\ndocker compose up -d   # start PostgreSQL, Redis, Meilisearch\nyarn install\nyarn initialize\nyarn dev\n```\n\nNavigate to `http://localhost:3000/backend` and sign in with the credentials printed by `yarn initialize`.\n\n### Add custom modules\n\nDrop your own modules into `src/modules/` and register them in `src/modules.ts` with `from: '@app'`:\n\n```ts\nexport const enabledModules: ModuleEntry[] = [\n  // ... core modules\n  { id: 'inventory', from: '@app' },\n]\n```\n\nRun `yarn generate` and `yarn dev` — your module's pages, APIs, and entities are auto-discovered.\n\n### Extend backend navigation with menu injection (SPEC-041 A/B)\n\nOpen Mercato now supports declarative menu injection for backend chrome surfaces without touching core files.\n\n1. Create a headless widget in your module:\n\n```ts\n// src/modules/example/widgets/injection/example-menus/widget.ts\nimport { InjectionPosition } from '@open-mercato/shared/modules/widgets/injection-position'\nimport type { InjectionMenuItemWidget } from '@open-mercato/shared/modules/widgets/injection'\n\nexport default {\n  metadata: { id: 'example.injection.example-menus', features: ['example.view'] },\n  menuItems: [\n    {\n      id: 'example-todos-shortcut',\n      label: 'example.menu.todosShortcut',\n      href: '/backend/example/todos',\n      groupId: 'example.nav.group',\n      groupLabelKey: 'example.nav.group',\n      placement: { position: InjectionPosition.Last },\n    },\n  ],\n} satisfies InjectionMenuItemWidget\n```\n\n2. Map it in `widgets/injection-table.ts`:\n\n```ts\nexport const injectionTable = {\n  'menu:sidebar:main': { widgetId: 'example.injection.example-menus', priority: 50 },\n  'menu:topbar:actions': { widgetId: 'example.injection.example-menus', priority: 50 },\n  'menu:topbar:profile-dropdown': { widgetId: 'example.injection.example-menus', priority: 50 },\n}\n```\n\n3. Run `yarn generate`.\n\nAvailable surfaces: `menu:sidebar:main`, `menu:sidebar:settings`, `menu:sidebar:profile`, `menu:topbar:actions`, `menu:topbar:profile-dropdown`.\n\n### Eject core modules for deep customization\n\nWhen 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.\n\n```bash\n# See which modules support ejection\nyarn mercato eject --list\n\n# Eject a module (e.g., currencies)\nyarn mercato eject currencies\nyarn mercato generate all\nyarn dev\n```\n\nCurrently ejectable: `catalog`, `currencies`, `customers`, `perspectives`, `planner`, `resources`, `sales`, `staff`, `workflows`.\n\nFull guide: [docs.openmercato.com/customization/standalone-app](https://docs.openmercato.com/customization/standalone-app) · CLI reference: [docs.openmercato.com/cli/eject](https://docs.openmercato.com/cli/eject)\n\n## Live demo\n\n[![Explore the Open Mercato live demo](./apps/docs/static/screenshots/open-mercato-onboarding-showoff.png)](https://demo.openmercato.com)\n\n## Documentation\n\nBrowse the full documentation at [docs.openmercato.com](https://docs.openmercato.com/).\n\n- [Introduction](https://docs.openmercato.com/introduction/overview)\n- [Installation](https://docs.openmercato.com/installation/setup)\n- [User Guide](https://docs.openmercato.com/user-guide/overview)\n- [Tutorials](https://docs.openmercato.com/tutorials/first-app)\n- [Customization](https://docs.openmercato.com/customization/build-first-app)\n- [Architecture](https://docs.openmercato.com/architecture/system-overview)\n- [Framework](https://docs.openmercato.com/framework/modules/overview)\n- [API Reference](https://docs.openmercato.com/api/overview)\n- [CLI Reference](https://docs.openmercato.com/cli/overview)\n- [Appendix](https://docs.openmercato.com/appendix/troubleshooting)\n\n## Spec Driven Development\n\nOpen Mercato follows a **spec-first development approach**. Before implementing new features or making significant changes, we document the design in the `.ai/specs/` folder.\n\n### Why Specs?\n\n- **Clarity**: Specs ensure everyone understands the feature before coding starts\n- **Consistency**: Design decisions are documented and can be referenced by humans and AI agents\n- **Traceability**: Each spec maintains a changelog tracking the evolution of the feature\n\n### How It Works\n\n1. **Before coding**: Check if a spec exists in `.ai/specs/` (named `SPEC-###-YYYY-MM-DD-title.md`)\n2. **New features**: Create or update the spec with your design before implementation\n3. **After changes**: Update the spec's changelog with a dated summary\n\n**Naming convention**: Specs use the format `SPEC-{number}-{date}-{title}.md` (e.g., `SPEC-007-2026-01-26-sidebar-reorganization.md`)\n\nSee [`.ai/specs/README.md`](.ai/specs/README.md) for the full specification directory and [`.ai/specs/AGENTS.md`](.ai/specs/AGENTS.md) for detailed guidelines on maintaining specs.\n\n## Join us on Discord\n\nConnect with the team and other builders in our Discord community: [https://discord.gg/f4qwPtJ3qA](https://discord.gg/f4qwPtJ3qA).\n\n## Contributing\n\nWe welcome contributions of all sizes—from fixes and docs updates to new modules. Start by reading [CONTRIBUTING.md](CONTRIBUTING.md) for branching conventions (`main`, `develop`, `feat/\u003cfeature\u003e`), release flow, and the full PR checklist. Then check the open issues or propose an idea in a discussion, and:\n\n1. Fork the repository and create a branch that reflects your change.\n2. 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).\n3. Develop and validate your changes (`yarn lint`, `yarn test`, or the relevant module scripts).\n4. Open a pull request referencing any related issues and outlining the testing you performed.\n\nRefer to [AGENTS.md](AGENTS.md) for deeper guidance on architecture and conventions when extending modules.\n\nOpen Mercato is proudly supported by [Catch The Tornado](https://catchthetornado.com/).\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://catchthetornado.com/\"\u003e\n    \u003cimg src=\"./apps/mercato//public/catch-the-tornado-logo.png\" alt=\"Catch The Tornado logo\" width=\"96\" /\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n## CLI Commands\n\nOpen Mercato let the module developers to expose the custom CLI commands for variouse maintenance tasks. Read more on the [CLI documentation](https://docs.openmercato.com/cli/overview)\n\n## Considering a project on Open Mercato?\n\nIf you're planning to build on Open Mercato, don’t go it alone.\n\n### Certified Partner Agencies\n\n**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.\n\nOur mission is simple: ensure every Open Mercato deployment is successful, secure, and scalable.\n\n## License\n\n- MIT — see `LICENSE` for details. Enterprise licensing details are documented in [`packages/enterprise/README.md`](packages/enterprise/README.md).\n\n## Enterprise Edition\n\nOpen Mercato Core is and always will be MIT Licensed, fully Open Source.\n\n### Open Mercato Enterprise Subscription\n\nThe Open Mercato Enterprise Subscription helps ensure your deployment is secure, scalable, and production-ready without surprises before go-live.\n\nIt combines certification, expert reviews, and ongoing advisory support for teams building serious systems on Open Mercato.\n\nWhat’s included:\n- Architecture \u0026 Production Readiness\n- Pre-deployment architecture audit\n- Production approval before go-live\n- Hosting and deployment best practices\n- Security \u0026 Quality (monthly reviews)\n- Customer Success Manager (pre-go-live)\n- Priority technical support channel\n- Platform Continuity - access to security patches and new features\n\nContact us to get support for your implementation: [info@openmercato.com](mailto:info@openmercato.com)\n\nEnterprise features are delivered under the `@open-mercato/enterprise` package (`/packages/enterprise`) and are not part of the open source license scope.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-mercato%2Fopen-mercato","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-mercato%2Fopen-mercato","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-mercato%2Fopen-mercato/lists"}