MerchOps is a calm operator console for Shopify merchants. It monitors your store for meaningful signals, surfaces prioritized opportunities, and drafts safe actions you can review and approve. Built for DTC operators managing $1M-$50M GMV stores who want leverage without losing control.

The core philosophy is simple: detect what matters, explain why it matters now, and execute only with your explicit approval. No autonomous sending, no hidden side effects, no black-box automation. Every opportunity shows its reasoning, every action shows its payload, and every execution is logged immutably.

+------------------+     +------------------+     +------------------+
|     Shopify      |     |    Webhooks      |     |     Events       |
|   (Your Store)   |---->|  orders/create   |---->| (Immutable Store)|
|                  |     |  products/update |     |  - dedupe_key    |
|                  |     |  inventory_levels|     |  - occurred_at   |
+------------------+     +------------------+     +------------------+
                                                          |
                                                          v
+------------------+     +------------------+     +------------------+
|    Outcomes      |     |   Executions     |     | Opportunities    |
| helped/neutral/  |<----|  (Immutable Log) |<----|  - why_now       |
| hurt + evidence  |     |  - idempotency   |     |  - counterfactual|
+------------------+     |  - retries       |     |  - priority      |
         ^               +------------------+     |  - decay_at      |
         |                        ^               +------------------+
         |                        |                       |
         |               +------------------+             v
         |               |    Approval      |     +------------------+
         +---------------|   (Human in      |<----| Action Drafts    |
                         |    the Loop)     |     |  - payload       |
                         +------------------+     |  - editable      |
                                                  +------------------+

Flow: Shopify --> Webhooks --> Events --> Opportunities --> Drafts --> Approval --> Execution --> Outcomes
                                                                           ^
                                                                           |
                                                              Nothing executes without this

Prerequisites:

• Node.js 20+ (LTS recommended)
• pnpm 8+ (npm install -g pnpm)
• Docker (for PostgreSQL and Redis)

Setup:

# Clone and install
git clone https://github.com/your-org/merchops.ai.git
cd merchops.ai
pnpm install

# Environment setup
cp .env.example .env.local
# Edit .env.local with your configuration

# Start infrastructure
docker compose up -d

# Database setup
pnpm prisma migrate dev
pnpm prisma generate

# Start app and workers
pnpm dev                    # Terminal 1
pnpm workers                # Terminal 2

Visit http://localhost:3000 to access the application.

Full guide: Local Development Documentation

Deploy MerchOps to production using any of these platforms:

Quick Deploy with Render:

1. Push code to GitHub
2. Deploy with Render Blueprint - render.yaml included
3. Set required environment variables
4. Run database migrations
5. Verify health check: https://your-app.onrender.com/api/health

Complete deployment guide: Deployment Documentation

Environment variables: Environment Variables Reference

Required:

• DATABASE_URL - PostgreSQL connection string
• REDIS_URL - Redis connection string for BullMQ
• NEXTAUTH_SECRET - Session encryption key (generate: openssl rand -base64 32)
• NEXTAUTH_URL - Application base URL
• SHOPIFY_CLIENT_ID - Shopify OAuth client ID
• SHOPIFY_CLIENT_SECRET - Shopify OAuth client secret
• SHOPIFY_SCOPES - OAuth scopes (see .env.example)
• SHOPIFY_WEBHOOK_SECRET - HMAC verification secret
• ENCRYPTION_KEY - Token encryption key (generate: openssl rand -hex 32)
• AI_PROVIDER - AI provider: anthropic, openai, or ollama
• ANTHROPIC_API_KEY or OPENAI_API_KEY - AI provider credentials
• EMAIL_PROVIDER_API_KEY - Resend/SendGrid API key

Optional:

• SENTRY_DSN - Sentry error tracking
• LOG_LEVEL - Logging verbosity (default: info)
• AI_MODEL_TIER - Model tier: fast, balanced, powerful (default: balanced)

Complete reference: Environment Variables Documentation

MerchOps provides interactive API documentation via Swagger UI.

• Swagger UI: Visit /api-docs in your browser
• OpenAPI Spec: Download at /openapi.yaml

All API endpoints (except /api/health) require session authentication. Login at /login to obtain a session cookie.

Every request includes an X-Correlation-ID header for tracing and debugging across services.

# Unit tests
pnpm test

# Unit tests in watch mode
pnpm test:watch

# E2E tests (requires running dev server)
pnpm test:e2e

# E2E tests with UI
pnpm test:e2e:ui

# Test coverage report
pnpm test:coverage

# Type checking
pnpm typecheck

# Linting
pnpm lint

# All quality checks (CI pipeline)
pnpm validate

Background workers process queued jobs for webhook ingestion, event computation, opportunity generation, and action execution.

# Start all workers
pnpm workers

# Start specific worker (if available)
pnpm worker:events
pnpm worker:opportunities
pnpm worker:executions

The root route (/) serves the MerchOps landing page for unauthenticated users. Authenticated users are automatically redirected to /queue.

All primary conversion buttons route to /signup?returnTo=/app:

• "Join the beta" (navigation, hero, final CTA)
• "Start your free trial" (final CTA)

After signup and login, users are redirected to the returnTo destination (defaults to /queue).

Copy and Tailwind classnames are contractually fixed to the Magic Patterns source. Do not modify styling or copy directly in the codebase.

To make changes:

1. Update the design in Magic Patterns
2. Export the updated code
3. Replace files in apps/web/components/marketing/
4. Preserve routing logic and event handlers

See apps/web/components/marketing/README.md for detailed component documentation.

/apps/web                    # Next.js application
  /app                       # App Router pages and layouts
    /(auth)                  # Authentication routes
    /(dashboard)             # Protected dashboard routes
  /components                # React components
    /marketing               # Landing page components (Magic Patterns source)
  /lib                       # Client utilities
  /server                    # Server-side code
    /auth                    # NextAuth configuration
    /db                      # Prisma client and queries
    /shopify                 # Shopify API integration
    /events                  # Event computation logic
    /opportunities           # Opportunity engine
    /actions                 # Draft and execution logic
    /jobs                    # BullMQ worker definitions
    /observability           # Logging and metrics
  /tests                     # Test files
    /unit                    # Unit tests (Vitest)
    /integration             # Integration tests
    /e2e                     # E2E tests (Playwright)

/packages/shared             # Shared code between apps
  /types                     # TypeScript type definitions
  /schemas                   # Zod validation schemas
  /prompts                   # AI prompt templates

/prisma                      # Database schema and migrations
  schema.prisma              # Prisma schema definition
  /migrations                # Migration files

/docs                        # Documentation
  /architecture              # System design documents
  /api                       # API documentation
  /security                  # Security documentation
  /verification              # Beta verification checklists

This is beta software. MerchOps is currently in active development and should not be used in production without thorough review.

• Single workspace per user (no multi-store support)
• Limited to supported event types and action types
• Email actions may require sandbox mode verification
• Performance under high load is not yet validated

If you encounter bugs or have feature requests:

1. Check existing issues in the repository
2. Create a new issue with:
   • Clear description of the problem
   • Steps to reproduce
   • Expected vs actual behavior
   • Relevant logs (sanitized of secrets)

For security vulnerabilities, please do not open a public issue. Contact the team directly at security@merchops.ai.

Proprietary. All rights reserved.

See CONTRIBUTING.md for development guidelines.