Skip to main content

​
Integrations

External service integrations for Syntropy Journals. Covers Shopify (partner + consumer), auth, payments, and analytics. Updated: 2026-03-28

​
Entity Model: Protocol-Product Relationship

In Syntropy Health, a Protocol is the primary entity — it represents a wellness usage plan (dosage, frequency, timing, duration). A ProtocolProduct is the underlying physical item (supplement, probiotic, device) that the protocol wraps. Key distinction:
  • ProtocolProduct = what you buy (a bottle of magnesium)
  • Protocol = how you use it (2 capsules, twice daily, with meals, 30 days)
  • UserProtocol = your commitment to follow it
  • ProtocolCheckIn = did you follow it today?
Code note: The DB model is currently Product (table product). A rename to ProtocolProduct is planned to align with domain language. Documentation uses ProtocolProduct as the canonical name.

​
Shopify Integration Overview

Two distinct Shopify integration paths serve different roles with different permissions and data flows.

​
Permission Matrix

​
Partner App (Shopify Protocols)

ScopePermissionWhat It AccessesDirection
read_productsShopify OAuthProduct titles, descriptions, variantsPull from Shopify
write_productsShopify OAuthProduct metafields (shrine_protocols namespace)Push to Shopify
integration:readJournals Bearer tokenAdherence stats, feedback, retentionPull from Journals
integration:writeJournals Bearer tokenProtocol CRUD (create, update, archive)Push to Journals

​
Consumer App (Individual User)

ScopePermissionWhat It AccessesDirection
Clerk JWTUser authConnect/disconnect/status/syncAll
(No Shopify OAuth)Via store URL onlyOrder line items → protocol extractionPull from Shopify

​
MCP Server (OpenClaw)

ScopePermissionWhat It AccessesDirection
health:readClerk JWT (OAuth 2.1)Subscribed protocols, check-in historyPull from Journals
health:writeClerk JWT (OAuth 2.1)Log check-ins, food entriesPush to Journals
(No Shopify access)N/AMCP never touches Shopify directlyN/A

​
Partner Data Flow

The partner flow starts at the Shopify store and ends with anonymized analytics flowing back.

​
Partner API Endpoints

MethodRouteAuthRateOperation
POST/api/v1/protocolsBearer (write)20/minCreate protocol
PUT/api/v1/protocols/{id}Bearer (write)20/minUpdate protocol
DELETE/api/v1/protocols/{id}Bearer (write)20/minArchive protocol
GET/api/v1/analytics/summaryBearer (read)60/minPartner-wide metrics
GET/api/v1/analytics/protocols/{id}/adherenceBearer (read)60/minPer-protocol adherence
GET/api/v1/analytics/protocols/{id}/feedbackBearer (read)60/minAnonymized feedback
GET/api/v1/analytics/protocols/{id}/retentionBearer (read)60/minCompletion funnel

​
Partner Auth Flow

​
Consumer Data Flow

The consumer flow starts when an individual user connects their Shopify store to sync supplement purchases.

​
Consumer API Endpoints

MethodRouteAuthOperation
POST/api/consumer/shopify/connectClerk JWTLink store URL
POST/api/consumer/shopify/syncClerk JWTTrigger order sync
GET/api/consumer/shopify/statusClerk JWTIntegration status
DELETE/api/consumer/shopify/disconnectClerk JWTSoft-delete integration

​
Shopify OAuth Flow (Partner Store Connection)

​
Data Privacy Boundary

Privacy rules:
  • Partners only see aggregate metrics, never individual user data
  • Users must opt-in (share_data_with_partner=true on UserProtocol)
  • Feedback is anonymized before partner access
  • No PII (email, name, health profile) crosses the boundary

​
Database Models

​
Secrets Setup (GitHub Actions → Railway)

Required secrets for CI/CD deployment. Add via Settings > Secrets and variables > Actions.
SecretWhere to get itRequiredSetup doc
RAILWAY_TOKENRailway Dashboard → Project-scoped tokenYes—
OPENAI_API_KEYOpenAI Dashboard or OpenRouterYes—
CLERK_SECRET_KEYClerk Dashboard → API Keys → Secret keyYesClerk API Token
STRIPE_SECRET_KEYStripe Dashboard → Secret key (sk_...)YesStripe + Clerk Subscription, reflex-stripe README (see monorepo libs/)
STRIPE_WEBHOOK_SECRETStripe Dashboard → Endpoint → Signing secret (whsec_...)NoStripe + Clerk Subscription
REFLEX_DB_URLSupabase Dashboard → Settings → Database → Connection string (Transaction mode)Yes—
TEST_DB_URLSame as above, test projectNo—
POSTHOG_PROJECT_API_KEYPostHog Dashboard → Project → Settings → API KeyNo—
HUBSPOT_API_KEYHubSpot Developer → Private App → Access tokenNo—
GitHub Variables (public, not secrets):
VariableWhere to get itSetup doc
CLERK_PUBLISHABLE_KEYClerk Dashboard → API Keys → Publishable key (pk_...)Clerk API Token
STRIPE_PUBLISHABLE_KEYStripe Dashboard → Publishable key (pk_...)reflex-stripe README (see monorepo libs/)
Environment-scoped secrets (Settings > Environments > prod or test):
SecretScopeWhy scoped
RAILWAY_TOKENPer environmentDifferent Railway project tokens for test vs prod
REFLEX_DB_URLPer environment (recommended)Different Supabase projects for test vs prod
Drift cleanup: deploy_railway.sh deletes Railway variables not in envs/template or envs/template.railway. Set DRY_RUN=true to preview.

​
Integration Docs

DocumentDescription
Shopify Protocol SyncCross-app data flow, metafield schema, sync tracking
Stripe + Clerk SubscriptionPayment processing, subscription tiers, Clerk metadata
Clerk API Token & PasscodeAPI tokens, 6-digit passcodes, external app integration
Junction WearablesWearable health scoring via Junction API
Call Logs APIDirectus-based call log ingestion pipeline
Amazon AffiliateProduct Advertising API integration
Google Tag ManagerAnalytics and tracking setup
Integration RoadmapWearable, CGM, EHR, purchase intelligence roadmap

​
Key Models

Integration-specific database models: 
syntropy_journals/app/data/schemas/db/models/integrations/
├── __init__.py
├── shopify_sync.py          # ShopifyProtocolSync
└── subscription.py          # UserProtocolSubscription
Core protocol/product models (extended with Shopify fields): 
syntropy_journals/app/models/syntropy/
├── protocol.py              # Protocol (+ timing, warnings, shopify_product_id, etc.)
└── product.py               # Product (+ shopify_product_id, price, sku)
Consumer integration tracking: 
syntropy_journals/app/functions/consumer/db_utils.py  # UserIntegration CRUD
syntropy_journals/app/api/routes/consumer_shopify.py  # REST endpoints
syntropy_journals/app/api/routes/shopify_oauth.py     # Partner OAuth flow