CarphaCom Whitepaper

1. Executive Summary

CarphaCom is a sovereign, European-built commerce, robotics and AI platform that ships as a single, one-click Vultr Marketplace image. It combines a Next.js 15 storefront, a Medusa v2 backend, a Postgres 16 + Redis 7 data plane, and a built-in marketplace that federates licensed plugins, themes and storefront templates from a central hub (carphacom.com) into independent tenant instances.

Where typical SaaS platforms force merchants into shared databases, opaque billing, and US-centric data residency, CarphaCom flips the model: every tenant runs on its own bare-metal box, owns its own database, pays a one-time license per plugin, and stores all data within the EU under a GDPR-native default.

2. Vision & Mission

Vision — A future where every European merchant, robotics integrator and AI builder can own the full stack they sell on, without surrendering data, margin, or velocity to hyperscalers.

Mission — Ship the world's most trustworthy turnkey commerce-and-automation OS: production-ready in a single click, hardened by default, and extensible by a federated marketplace of vetted plugins.

3. The Problem

Data sovereignty erosion. SaaS storefronts and AI agents send EU customer data to non-EU clouds, exposing merchants to GDPR, NIS2 and DORA risk.
Margin extraction. Marketplaces and SaaS billing siphon 2.5%–15% of GMV plus per-seat fees, indefinitely.
Vendor lock-in. Proprietary admin UIs, opaque schemas, and undocumented APIs make migration practically impossible.
Robotics & AI silos. Commerce, robotics fleets and AI assistants are sold as disconnected products, forcing custom integration on every customer.

4. The CarphaCom Solution

CarphaCom delivers four tightly integrated layers as one image:

Storefront — Next.js 15 (App Router), i18n-aware, Tailwind + shadcn/ui, edge-cached, OWASP-hardened.
Backend — Medusa v2, Postgres 16, Redis 7, BullMQ workers, full event log.
Admin Panel — Independent Next.js admin at /app, built-in CMS, SEO, marketing automation, supplier sync.
Marketplace Federation — Tenant installed/ registry that pulls signed plugin/theme tarballs from carphacom.com and activates them transactionally in the database.

5. Architecture Overview

5.1 Three-tier separation

[ MAIN — carphacom.com ]
   ├─ License issuer (Stripe-billed)
   ├─ Plugin/theme registry (signed tarballs + SHA-256)
   └─ Federated feed (/store/marketplace/feed)

[ TENANT — beta.carphacom.com / customer-instance.tld ]
   ├─ pm2: carphacom-storefront (8000)
   ├─ pm2: carphacom-admin      (3001, basePath=/app)
   ├─ pm2: carphacom-backend    (9000, Medusa v2)
   ├─ Postgres 16 + Redis 7
   └─ /opt/carphacom/installed/ (plugin/theme working tree)

[ EDGE ]
   ├─ Nginx + Let's Encrypt (auto-SSL plugin)
   ├─ HSTS preload, CSP enforced, X-Frame-Options DENY
   └─ OCSP stapling, HTTP/2

5.2 Federated install flow

Admin clicks "Install" on a marketplace card.
Admin POST /app/api/marketplace/install with {marketplace_id, force}.
Server resolves the canonical tarball URL from the MAIN feed, downloads via 3-candidate fallback chain, verifies SHA-256.
Tar extracts to /opt/carphacom/installed/<slug>/.
Database row inserted in cms_plugin or cms_theme (theme activation uses a 2-step UPDATE).
Storefront ISR revalidation triggered.

6. Security & Compliance

Transport — TLS 1.3, HSTS max-age=63072000; includeSubDomains; preload, OCSP stapling.
Headers — Enforced Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, Permissions-Policy minimised.
Authentication — Built-in admin rate-limit (5/IP/5min → 15min lockout), Argon2id password hashing, opt-in TOTP 2FA.
OWASP — Automated pentest scan verified 0 Critical / 0 High / 0 Medium / 0 Low across 19 admin routes and 35 storefront routes.
Accessibility — axe-core scan verified 0 critical/serious WCAG violations across primary surfaces.
Data residency — All Vultr regions in scope are EU (Frankfurt, Amsterdam, Paris, Madrid, Warsaw, Stockholm).
GDPR — DSAR export endpoint, right-to-erasure cascade across orders, addresses, sessions.

7. Marketplace & Federation

CarphaCom's marketplace is a federation, not a walled garden. Plugin authors publish to carphacom.com; tenants pull artefacts and activate them locally. Each plugin manifest declares:

marketplace_id (e.g. @carphacom/stripe-payment)
version (semver)
type — payment, fulfillment, b2b-api, admin-extension, notification, tax, auth, analytics, storefront-widget, storefront-template, and more.
price_eur and one_time_payment flag
SHA-256 of the tarball

Tenants pay once per plugin per instance. There is no recurring marketplace tax. Updates are opt-in.

8. Plugin & Theme System

Themes are flat tar.gz archives extracted under installed/<slug>/. The storefront reads the active theme from cms_theme.is_active and resolves CSS overrides at request time. Plugin lifecycles support install, activate, deactivate, uninstall hooks executed in a Postgres transaction.

Theme activation uses a 2-step UPDATE (clear all is_active, then set one) to satisfy the partial unique index WHERE is_active = true.

9. Robotics & AI Layer

CarphaCom is designed to host commerce and the autonomous fleets that fulfil it. The Robot HAL and 130+ communication protocol stack live in the QubitPage AIOS — a #![no_std] Rust microkernel — and connect to CarphaCom over the Qavatar Protocol (port 7777, AES-256-GCM). Federated AI agents built on Microsoft Foundry plug into Medusa workflows for catalog enrichment, ticket triage, fraud signals and supplier price optimisation.

10. Deployment & One-Click Install

The Vultr Marketplace image bootstraps in under 8 minutes:

Provision instance, attach EU region.
Cloud-init installs Postgres 16, Redis 7, Node 20, pm2, nginx, certbot.
Pulls the latest stable release from carphacom.com/releases/stable-2026.04.
Runs DB migrations, seeds the demo catalog (optional).
Issues Let's Encrypt cert via the bundled auto-ssl plugin.
Returns admin credentials and the public URL.

11. Roadmap

2026.05 — Multi-region active-active replication for marketplace metadata.
2026.06 — In-admin wizard for white-label re-skinning under partner brands.
2026.07 — Robotics fleet dashboard module (live telemetry, OTA flashing).
2026.08 — On-prem Foundry agent runner inside tenant boxes.

12. Glossary

MAIN: The federation hub at carphacom.com.
BETA / Tenant: An independent CarphaCom instance.
Federation feed: GET /store/marketplace/feed endpoint listing all installable artefacts.
CcFooter / CcShell: The corporate v2 layout primitives (data-cms-corporate="v2").
Qavatar Protocol: AES-256-GCM control channel between AIOS nodes and CarphaCom tenants.