CarphaCom Marketplace

1. Executive Overview

CarphaCom is a complete e-commerce platform that ships with a native marketplace for third-party Themes and Plugins, multilingual content management, and a developer revenue-share program — all packaged for one-click deployment via Vultr Marketplace.

Key Capabilities

2. System Architecture

Three-tier architecture with clear separation between presentation (Next.js), business logic (Medusa v2 modules), and persistence (Postgres + Redis).

Process Manager (PM2)

3. Technology Stack

100% open standards, zero vendor lock-in, fully type-safe end-to-end.

4. Data Model

All marketplace data lives in dedicated cms_* tables alongside Medusa core tables. Single Postgres database — no microservice fragmentation.

cms_theme

CREATE TABLE cms_theme (
    id            TEXT PRIMARY KEY,
    slug          TEXT UNIQUE NOT NULL,
    name          TEXT NOT NULL,
    version       TEXT NOT NULL,
    description   TEXT,
    author        TEXT,
    preview_url   TEXT,
    install_path  TEXT NOT NULL,        -- /opt/carphacom/themes/<slug>
    manifest      JSONB NOT NULL,        -- full manifest.json contents
    is_active     BOOLEAN NOT NULL DEFAULT FALSE,
    status        TEXT NOT NULL DEFAULT 'approved',  -- pending|approved|rejected
    commission_pct INTEGER NOT NULL DEFAULT 10,      -- platform cut %
    submitted_by  TEXT,                  -- dev account email
    installed_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
    activated_at  TIMESTAMPTZ,
    approved_at   TIMESTAMPTZ
);
-- Only ONE theme can be active at a time
CREATE UNIQUE INDEX cms_theme_one_active
    ON cms_theme ((is_active)) WHERE is_active = TRUE;

cms_plugin

CREATE TABLE cms_plugin (
    id            TEXT PRIMARY KEY,
    slug          TEXT UNIQUE NOT NULL,
    name          TEXT NOT NULL,
    version       TEXT NOT NULL,
    description   TEXT,
    author        TEXT,
    install_path  TEXT NOT NULL,
    manifest      JSONB NOT NULL,
    is_enabled    BOOLEAN NOT NULL DEFAULT FALSE,
    status        TEXT NOT NULL DEFAULT 'approved',
    commission_pct INTEGER NOT NULL DEFAULT 10,
    submitted_by  TEXT,
    installed_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
    enabled_at    TIMESTAMPTZ,
    approved_at   TIMESTAMPTZ
);

cms_i18n_string (shared admin + storefront)

CREATE TABLE cms_i18n_string (
    id     BIGSERIAL PRIMARY KEY,
    scope  TEXT NOT NULL,                 -- 'admin' | 'storefront' | 'theme:<slug>'
    locale TEXT NOT NULL,                 -- 'ro' | 'en' | 'de'
    key    TEXT NOT NULL,
    value  TEXT NOT NULL,
    UNIQUE(scope, locale, key)
);

cms_dev_account

CREATE TABLE cms_dev_account (
    id              TEXT PRIMARY KEY,
    email           TEXT UNIQUE NOT NULL,
    name            TEXT NOT NULL,
    company         TEXT,
    payout_method   TEXT,                 -- 'stripe' | 'wire' | 'paypal'
    payout_details  JSONB,                -- { iban, swift, ... }
    api_key         TEXT UNIQUE NOT NULL, -- for ZIP submission API
    created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    approved        BOOLEAN NOT NULL DEFAULT FALSE
);

5. REST API Reference

All endpoints documented below are live on production at https://carphacom.com.

Auth — PUBLIC

Admin — CMS Themes JWT REQUIRED

Admin — CMS Plugins JWT REQUIRED

Store — Public

Example: Install Theme via API

# 1. Login
TOKEN=$(curl -sS -X POST https://carphacom.com/api/medusa/auth/user/emailpass \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@carphacom.com","password":"Admin#2026Pass"}' | jq -r .token)

# 2. Encode ZIP to base64
B64=$(base64 -w0 my-theme.zip)

# 3. Upload
curl -X POST https://carphacom.com/api/medusa/admin/cms/themes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"zip_b64\":\"$B64\"}"

6. CMS Engine

A custom CMS layer sits on top of Medusa, providing dynamic content, themes, plugins, and i18n — all driven from a unified cms_* namespace in Postgres.

Content Pipeline

1. SSR Render — every page request triggers a getActiveTheme() + getActivePlugins() Postgres query.
2. Theme Shell — CmsThemeShell.tsx wraps every page, injecting CSS variables and theme classes.
3. Plugin Renderer — CmsPluginRenderer.tsx outputs all enabled plugins as SSR HTML.
4. i18n Loader — getThemeStrings(locale) reads {installPath}/lang/{locale}.json with default-locale fallback.
5. ISR Revalidation — admin operations call POST /api/revalidate to flush Next.js cache.

Cache Strategy

• Pool singleton — one pg.Pool per Node process, stored on globalThis.__cmsPool.
• ISR — homepage, product, category routes use force-dynamic + revalidate=0 due to cookies() usage.
• Static assets — /marketplace-files/* served by nginx with 7-day cache headers.

7. Theme System

A Theme is a ZIP archive containing a manifest.json, optional style.css, and per-locale lang/*.json files. The active theme controls colors, fonts, layout, and language strings storefront-wide.

How to Build a Theme

Create a folder structure:

my-theme/
├── manifest.json          # required
├── style.css              # optional global overrides
├── preview.png            # optional preview image
└── lang/
    ├── ro.json
    ├── en.json
    └── de.json

manifest.json schema

{
  "slug": "my-cool-theme",                  // unique, lowercase, [a-z0-9-]
  "name": "My Cool Theme",
  "version": "1.0.0",
  "description": "A modern minimalist theme",
  "author": "Your Name",
  "default_locale": "ro",
  "locales": ["ro", "en", "de"],
  "css_vars": {
    "--theme-primary":   "#6366f1",
    "--theme-secondary": "#22d3ee",
    "--theme-font":      "Inter, system-ui, sans-serif",
    "--theme-radius":    "12px"
  },
  "layout_style": "modern",                 // modern|luxury|fashion|b2b
  "preview_url": "/marketplace-files/themes/my-cool-theme.png"
}

Build the ZIP

cd my-theme
zip -r ../my-theme.zip .

Install from Admin UI

1. Log in to https://carphacom.com/app
2. Sidebar → Themes
3. Click Upload theme, select your .zip
4. Click Activate on the new theme card — storefront updates instantly

Built-in Themes

8. Plugin System

Plugins are SSR-rendered widgets injected globally into every page (currently): banners, popups, badges, chat boxes, etc. Each plugin is a ZIP with manifest + render template.

Plugin Structure

my-plugin/
├── manifest.json
├── index.js               # CommonJS module exporting render()
└── template.html          # static HTML (used by SSR)

manifest.json

{
  "slug": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "Does cool stuff",
  "author": "Your Name",
  "type": "banner",                  // banner|popup|badge|chat
  "config": { /* plugin-specific */ },
  "entry": "index.js",
  "render": "server-html"
}

Reference: Free Shipping Bar Plugin

<div style="background:linear-gradient(90deg,#10b981,#059669);
            color:#fff;padding:8px;text-align:center;font-weight:600">
  🚚 Livrare gratuită la comenzi peste 150 RON
</div>

module.exports = {
  render: () => require('fs').readFileSync(__dirname + '/template.html', 'utf8')
};

Live Production Plugins

9. Internationalization (i18n)

Single shared language file scope both admin and storefront — change the global locale once and every UI string updates.

Architecture

• Per-theme strings — bundled inside theme ZIP at lang/{locale}.json.
• Shared UI strings — stored in cms_i18n_string table with scope column (admin | storefront | shared).
• Storefront loader — getThemeStrings(locale) reads from filesystem with default-locale fallback.
• Admin loader — useI18n(scope) hook fetches from API at mount.

Switch Global Language (Admin)

1. Sidebar → Settings → Language
2. Select language: 🇷🇴 Română · 🇬🇧 English · 🇩🇪 Deutsch
3. Click Apply globally — admin AND storefront switch immediately

Add a New Language

INSERT INTO cms_i18n_string (scope, locale, key, value) VALUES
  ('shared', 'fr', 'shop_now',     'Acheter maintenant'),
  ('shared', 'fr', 'add_to_cart',  'Ajouter au panier'),
  ('shared', 'fr', 'welcome',      'Bienvenue!');

10. Developer Portal

Third-party developers can register, submit themes/plugins, and earn 90% of every sale.

Sign Up Flow

1. Visit https://carphacom.com/developers/signup
2. Submit: name, email, company, payout method (Stripe/IBAN/PayPal)
3. Receive API key by email — store securely
4. Wait for admin approval (typically < 24h)

Submit a Theme via API

curl -X POST https://carphacom.com/api/dev/themes/submit \
  -H "X-Dev-Api-Key: $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"zip_b64\":\"$(base64 -w0 my-theme.zip)\"}"
# Response: { "id": "thm_...", "status": "pending" }

Revenue Split

11. Approval Workflow

Every submitted Theme or Plugin enters a moderated review pipeline before becoming visible in the public marketplace.

Auto-checks (run on submission)

• Manifest validity — slug, name, version required, semver-compliant
• ZIP size limit — themes ≤ 5 MB, plugins ≤ 2 MB
• No executable binaries
• No external network calls in index.js (static analysis)
• CSS lint — no @import url(http...)
• HTML sanitization — strip <script> from template.html

12. Admin Panel

Custom Next.js 15 admin (port 3001) accessible at https://carphacom.com/app.

Login Credentials (default)

Email:    admin@carphacom.com
Password: Admin#2026Pass

Sidebar Modules

13. Deployment

One-click Vultr Marketplace deployment, or manual install on any Ubuntu 22.04+ VM.

Vultr One-Click

1. Visit vultr.com/marketplace/apps/carphacom
2. Select region & instance size (min 4 vCPU / 8GB RAM)
3. Deploy — installer provisions Postgres, Redis, nginx, PM2, certs in ~5 min
4. Open returned URL → admin signup wizard

Manual Install

# Ubuntu 22.04+
curl -fsSL https://carphacom.com/install.sh | sudo bash
# Installer:
#  - apt: nodejs 20, postgresql-16, redis-server, nginx
#  - createdb medusa_store, ALTER USER medusa
#  - clone repos to /opt/carphacom/current/
#  - npm install + npm run build
#  - pm2 start ecosystem.config.js
#  - certbot --nginx -d yourdomain.com

14. Security Posture

Production-hardened against OWASP Top 10. Continuous static + dynamic security testing.

• HTTPS-only — HSTS preload, TLS 1.3, automatic Let's Encrypt renewal
• Auth — bcrypt-hashed passwords, JWT with 1h expiry + refresh, optional MFA (TOTP)
• RBAC — admin / dev / customer roles with scoped permissions
• Rate limiting — nginx limit_req_zone 100 req/min per IP, +25 burst
• SQL injection — 100% parameterized queries via pg driver
• XSS — React auto-escapes; only sanitized HTML enters dangerouslySetInnerHTML
• CSRF — same-site cookies + token validation on state-mutating requests
• Plugin sandbox — plugins are SSR-rendered server-side; no arbitrary client JS execution
• File uploads — magic-byte validation, virus scan via ClamAV
• Secret storage — env vars only; .env never committed; secrets in Vault optional

15. Robot-Ready API AGENT-FIRST

CarphaCom is built for autonomous LLM agents. Every operation surfaced in the admin UI also exposes a clean REST endpoint with deterministic JSON I/O.

Agent Tool Catalog

Agents (Sentinel Coder, Claude, GPT) can integrate directly via these tool-style endpoints:

Agent Authentication

POST /auth/user/emailpass
Content-Type: application/json
{
  "email": "agent@carphacom.com",
  "password": "<agent_secret>"
}
→ { "token": "eyJ..." }   // Use as Authorization: Bearer <token>