← Back to Marketing Page

Matjar Platform Reference & User Guide

Welcome to the official Matjar Omnichannel E-Commerce Suite user and developer documentation. Matjar is a white-label, highly-configurable retail system designed to bridge customer-facing web stores, offline-first register touchscreens (POS), and a unified administrative back-office into a single database backend.

💡 System Architecture Overview

Matjar maintains exactly one backend API as the single source of truth. All storefront clients, registers, and administrative tools operate as thin clients interacting with the API via JWT authentication and REST endpoints.

Project Sub-Modules

Module Name Primary Stack Default Port Target Audience
matjar-api Express.js, Sequelize, MySQL, Redis 5001 Engineers / Core services
matjar-web Next.js 16 (App Router), Tailwind CSS 3000 Online Customers
matjar-admin React 19, Vite 6, Tailwind CSS 3002 Store Managers / Staff
matjar-pos React 19, Vite, IndexedDB (PWA) 3001 Cashiers / Register registers
matjar-email-templates React Email, Nodemailer 3003 (preview) Internal Notifications

New Client Installation

Setting up the Matjar suite for a brand-new client requires completing the database configurations and environment settings. Follow these step-by-step setup instructions to instantiate a fresh server for your next customer.

Prerequisites

1. Initial Repository Setup

First, clone the repositories and install dependencies in the respective project roots. Crucially, compile the email templates first, as the Express backend directly imports and relies on these templates for sending emails:

# 1. Compile email templates
cd matjar-email-templates
npm install
npm run build

# 2. Setup the backend API gateway
cd ../matjar-api
npm install

2. Configure Environment Variables

Create a .env file in the matjar-api/ root. Below is a complete configuration template suitable for setting up a client environment:

NODE_ENV=development
PORT=5001

# Branding & URLs
STORE_NAME=YourStore
STORE_DOMAIN=yourdomain.com
STORE_URL=http://localhost:3000
API_URL=http://localhost:5001
CORS_ORIGINS=http://localhost:3000,http://localhost:3001,http://localhost:3002

# Database Connection
DB_HOST=localhost
DB_PORT=3306
DB_NAME=matjar
DB_USER=root
DB_PASSWORD=YourSecureDatabasePassword123!

# JWT Credentials
JWT_SECRET=your-random-64-byte-hex-string
JWT_EXPIRE=15m

# Transactional Email SMTP
SMTP_HOST=smtp.your-provider.com
SMTP_PORT=587
SMTP_USER=noreply@yourdomain.com
SMTP_PASS=your-smtp-password
SMTP_FROM=noreply@yourdomain.com
EMAIL_TEMPLATES_DIST=../matjar-email-templates/dist/index.js
⚠️ Security Notice

For production environments, ensure that you set NODE_ENV=production and generate a cryptographically secure 64-character hex string for the JWT_SECRET. You can generate one via: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))".

Migrations & Seeds

Matjar uses an idempotent, transaction-safe migration runner that keeps track of executed scripts inside the SequelizeMeta table. Fresh installations run clean schema syncs before executing feature updates.

1. Database Setup

Create your client's databases inside your MySQL server. You can execute this directly via command line or MySQL workbench:

CREATE DATABASE IF NOT EXISTS `matjar` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE IF NOT EXISTS `matjar_test` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

2. Running Database Migrations

Execute the following script from the root of matjar-api. This will sync the latest database structures, build tables, and apply any schema changes:

# Run from matjar-api
npm run migrate

3. Seeding the Core Administrator

Seed the initial administrative user using the environment variables defined in your .env file (or using defaults):

# Seed the bootstrap administrator
npm run seed:bootstrap

Once seeded, you can sign in to the Admin Dashboard (matjar-admin) using the seeded credentials to begin configuring shipping zones, taxes, currency codes, and custom layouts.

Pilot Launch & Seeding

For the first pilot rollout (such as the Nusoky pilot merchant), you can seed a complete, pre-configured database catalog directly into your development or testing environment to skip manual inventory entry.

1. Load the Nusoky Pilot Catalog

Run the seed script inside `matjar-api` to populate the database with the pilot catalog:

# Run from matjar-api
npm run seed:nusoky

This script seeds the following parameters into your environment:

2. Verifying the Seed Data

To verify the data loaded successfully, query the database using the Sequelize CLI or MySQL client:

mysql -u root -p -e "SELECT COUNT(*) FROM matjar.products;"
# Should output: 138

API & Developer Reference

Developers implementing custom integrations or maintaining the frontends must adhere to the standard REST specifications defined by the core gateway.

Public and Gated Access Scopes

API Base Endpoint HTTP Methods Required Scopes Description
/api/v1/auth/* GET, POST, PATCH Public / User Token User registration, login, profile updates, POS PIN login
/api/v1/products/* GET Public Catalog browsing, faceted search, variant lookup
/api/v1/cart/* GET, POST, DELETE Public / Customer JWT Cart items updates, coupon code validations, checkout request
/api/v1/admin/* GET, POST, PATCH, DELETE Staff+ / Admin JWT Oversight, inventory adjustments, orders fulfillment, settings updates
/api/v1/pos/* GET, POST, PATCH Staff+ JWT Shift opening/closing, register sales, cash movements

Translation Files (i18n)

To add bilingual translation support, update the following translation files simultaneously. Keys must remain in parity between them:

Production Deployment Checklist

Before launching your client on a live server, ensure that the following production readiness tasks have been fully completed:

  1. Force Production Mode: Set NODE_ENV=production on all service processes.
  2. Secure JWT Signing: Generate a custom 64-character JWT token secret and set JWT_EXPIRE=15m.
  3. SSL Certification: Wrap all domains (api, pos, admin, storefront) with Let's Encrypt SSL certificates.
  4. Configure Payment Webhooks: Configure Stripe/PayTabs webhook secrets in the admin settings panel to ensure asynchronous payment completions.
  5. Verify SMTP Connection: Run testing tools to confirm that the SMTP configuration successfully dispatches transactional emails.

For a detailed breakdown of server configurations, refer to the ops guides in docs/ops/PRODUCTION.md.