Architecture Overview

This is the source of truth for how the Swapps Platform fits together and is deployed. The individual repositories describe each component in depth; this section describes how they integrate as a whole.

Swapps Platform is composed of four independent applications — each with its own repository and deployment cycle — plus WordPress as the blog CMS, all behind Cloudflare as the entry layer (security + routing).

Component Role Repository Hostname (prod) Stack
Website Public site (SSR) swappsco/swapps-client swapps.com React 19 + Vite + Vike on Cloudflare Workers
App Client platform / project management swappsco/idk app.swapps.com Django 5 (Python 3.12) + Celery + Postgres + Redis
Platform Serverless API / site backend swappsco/swapps-worker swapps-worker.swapps.workers.dev Cloudflare Workers + Hono + TypeScript
AI AI recommendations & refinement swappsco/swapps-ai swapps.com/api/ai/* Cloudflare Workers + Workers AI + AI Search
Blog / CMS Blog & marketing pages swappsco/wp-swappscom swapps.com/wp-*, swapps.com/wp-json/* WordPress (PHP 8.3) on Pantheon

The whole platform at a glance

flowchart TD User([User]) subgraph Edge["Cloudflare (edge)"] CF["DNS · WAF · TLS · Cache · Bot mgmt
Workers Routes (route by hostname + path)"] end User --> CF CF -->|"swapps.com/* (rest of the site)"| Website CF -->|"swapps.com/api/ai/*"| AI CF -->|"swapps.com/wp-* · /wp-json/* · /health"| WP CF -->|"app.swapps.com/*"| App Website["WEBSITE
swapps-client
(Workers, SSR)"] AI["AI
swapps-ai
(Workers AI)"] WP["WORDPRESS
(Pantheon · WP)"] App["APP (Django)
app.swapps.com
K8s / Argo CD"] Platform["PLATFORM
swapps-worker
(Workers + Hono)"] Website -->|"Service Binding (API_WORKER)"| Platform Website -->|"fetch (subscriptions, checkout)"| App Website -->|"fetch /api/ai/*"| AI Platform -->|"WP REST API (read posts)"| WP Platform -->|"Pipedrive · Mailgun · V0 · LiteLLM · Agno · ClickUp"| PExt[(External services)] App -->|"Stripe · ClickUp · Toggl · Pipedrive · QuickBooks · FrontApp · AGNO · S3 · Mailgun · OneSignal"| AExt[(External services)]

Flow in brief

  1. All traffic enters through Cloudflare (DNS, WAF, TLS, cache). It is the only exposed layer and where perimeter security is applied.
  2. Cloudflare routes by hostname and path via Workers Routes (see Cloudflare Edge): the site goes to the Website, WordPress routes to the CMS, /api/ai/* to the AI worker, and app.swapps.com to the App.
  3. The Website (swapps-client) talks to the Platform worker via a Service Binding (API_WORKER, Worker→Worker, no public hop) for blog, leads, support and chat; to the App via direct fetch for subscriptions and checkout; and to the AI worker for project recommendations.
  4. The Platform worker consumes the WP REST API to serve blog content to the site, and orchestrates external integrations (Pipedrive, Mailgun, etc.).

How the projects communicate

From To Mechanism Purpose
Website Platform Service Binding API_WORKER → swapps-worker Blog, leads, support, chat (Worker→Worker, no public HTTP)
Website App fetch to SUBSCRIPTIONS_API_URL (https://app.swapps.com) Subscription plans and checkout sessions
Website AI fetch to /api/ai/* Project recommendations and AI description refinement
Platform WordPress fetch to the WP REST API (https://swapps.com/wp-json/wp/v2) Fetch posts/authors/tags for the blog
App External SDK / REST Stripe, ClickUp, Toggl, Pipedrive, QuickBooks, FrontApp, AGNO, S3, Mailgun, OneSignal
External App Inbound webhooks (POST, server-to-server) ClickUp, Stripe and Zapier → app.swapps.com (need a WAF Skip exception)
Platform External REST Pipedrive (CRM), Mailgun (email), V0 (prototypes), LiteLLM, Agno, ClickUp

See Service Communication for the full detail and integration gotchas.

Repositories

Mirror monorepo

swappscom-website aggregates Website + Platform in a single repo to work them together with GitHub Copilot. No production service depends on it; the source of truth remains each individual repo.

Where to go next