Swapps Platform Documentation

This site is the single source of truth for how the Swapps Platform is built, how its services integrate, and how everything is deployed. It consolidates the documentation of every component into one place:

For the platform-wide picture — how requests are routed, how services talk to each other, and how each piece is deployed — start with the Architecture section.

What the platform is

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 idk placeholder name

The local folder name idk is a placeholder; the project is the Swapps App served at app.swapps.com.

High-level architecture

flowchart TD User([User]) CF["Cloudflare edge
DNS · WAF · TLS · Cache · Workers Routes"] User --> CF CF -->|swapps.com/*| Website["Website
swapps-client
(Workers, SSR)"] CF -->|swapps.com/api/ai/*| AI["AI
swapps-ai
(Workers AI)"] CF -->|/wp-* · /wp-json/*| WP["WordPress
(Pantheon)"] CF -->|app.swapps.com/*| App["App
Django
(K8s / Argo CD)"] Website -->|Service Binding API_WORKER| Platform["Platform
swapps-worker
(Workers + Hono)"] Website -->|fetch checkout/subscriptions| App Website -->|fetch /api/ai/*| AI Platform -->|WP REST API| WP Platform -->|Pipedrive · Mailgun · V0 · ClickUp| Ext[(External services)] App -->|Stripe · ClickUp · Toggl · Pipedrive · QuickBooks · …| Ext

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: 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 talks to the Platform worker through 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.).

See the Architecture Overview for the full picture.

Documentation map

Section What you'll find
Architecture Whole-platform design: edge routing, service communication, environments, deployment, observability.
Website swapps-client — React SSR on Workers: getting started, architecture, features.
App swapps-app / IDK — Django modules, async tasks, integrations, API, runbooks.
Platform swapps-worker — Hono API: endpoints, integrations, key flows.
AI swapps-ai — Workers AI plan recommendations and RAG.
Landing swapps-campaigns — marketing/campaigns site on Cloudflare Pages.
App MCP swapps-app-mcp — read-only Python MCP server over the App API.
MCP Worker swapps-mcp-worker — TypeScript MCP server on Cloudflare Workers.
Blog / CMS WordPress on Pantheon and how it fits the site.

Source repositories

Each component lives in its own repository. This site consolidates their documentation; the canonical code stays in each repo. See Architecture → Overview for links.