Architecture

A one-page tour of the moving parts. Source of truth lives in STRATEGY_v3.md (private internal repo) — this page is the publishable summary.

Runtimes

• Cloudflare Workers — public-facing routes at api.hygoshop.com. Stateless, horizontally autoscaled, deployed via Wrangler.
• Cloudflare Pages — three projects: hygoshop-com (marketing, this site), hygoshop-docs (these docs), hygoshop-status (uptime page).
• Postgres — canonical relational store. Cloudflare-Tunneled droplet for production; Neon as the provider-portable fallback.
• Hyperdrive — connection pool + read cache in front of Postgres so Workers don't hold idle connections.
• R2 — object storage for binary content (generated images, label PDFs, attachment uploads).
• Cloudflare Queues — async batch ingest, AI re-score jobs, notification fan-out.
• KV — short-TTL cache for auth introspection, feature-flag reads.

Application packages

• @hygoshop/canonical — canonical type contracts (Tenant, Listing, Order, OperatorTask, ...). Every other package imports types from here. No package imports another's internals.
• @hygoshop/workflow-runtime — pause / resume / claim / fail mechanics for long-running workflows that may hand off to a human operator.
• @hygoshop/workflows — concrete workflow definitions: launch product, recover abandoned cart, predict reorder, agent-readiness remediation.
• @hygoshop/router — picks an adapter implementation per-tenant by tier × cost × health × explicit override.

Adapters

Every external service is wrapped in an adapter package. Adapters implement category interfaces:

• CommerceAdapter — Shopify, WooCommerce, BigCommerce, Amazon SP-API
• SocialAdapter — Ayrshare (covers Instagram, TikTok, YouTube, Facebook, X, LinkedIn, Pinterest, ...)
• LlmAdapter — Anthropic Claude, OpenAI, OpenRouter, local
• ImageGenAdapter — Replicate, OpenAI Images, ...
• PaymentsAdapter — Stripe + Stripe Connect
• ShippingAdapter — EasyPost, ShipStation
• TaxAdapter — TaxJar, Avalara
• EmailAdapter — Resend, Postmark, SendGrid
• WorkflowAdapter — internal workflow-runtime (always present)

No vendor SDK is imported outside its adapter package. This keeps the contract surface narrow and lets us add or swap providers without rewrites.

Storefront

Medusa 2.x runs as the storefront-side application layer. The Medusa app lives in apps/medusa/ and is owned by tenants who choose Medusa for their headless commerce front. The shared @hygoshop/canonical package is the contract between Medusa and Hygoshop's worker-side services.

Multi-tenant boundaries

Every persisted row carries a tenant_id. Workers enforce tenant scoping at the route layer; Postgres row-level security gives a defense-in-depth check. Cross-tenant reads are explicitly rejected.

Observability

OpenTelemetry traces ship to a central collector. Worker invocations, queue jobs, and adapter calls all emit spans tagged with tenant_id so per-tenant performance + error patterns are inspectable.

What lives where

Concern	Location
Canonical types	packages/canonical/
Worker route handlers	apps/worker/
Adapter packages	packages/adapter-*/
Workflows	packages/workflows/
Marketing site	web_contents/site-template/ (sibling repo)
Docs (this site)	apps/docs/
Status page	apps/status/
Internal Medusa app	apps/medusa/