dx-maps — one build, maps that embed everywhere

Write a map once in plugin-designs/<your-map>/, run one build, and drop it on any site — iframe, script embed, mobile app — or open every map at once as one app. Five plugin capabilities, five deployment methods, one shared library, one build.

What dx-maps set out to do	Proof
One build → one folder you can drop on any host	bun run check:drop
Every map embeddable from a copy-paste snippet	deployment methods · bun run check:embed-targets
Every map interoperable through props and events	bun run verify:interop
One app nests every map — and each stays embeddable on its own	capability 5 · bun run check:composite-reg
5 capabilities × 5 deployment methods	bun run verify:5-caps
Shared library, private plugins — reuse without breaking each other	bun run check:library-index
One agent per plugin, one shepherd, one green main	agent swarm

---

The 5 plugin capabilities

A capability is how much a plugin nests, from one element (1) to an app of apps (5). Every screenshot is a real bundle from this repo's build.

Capability 5 — app shell: the Research Gallery

One plugin, one element (<doxa-maps-spa>), and every tab inside it is a real plugin from a lower tier that you can still embed on its own. plugin-designs/doxa-maps-spa/

What the Research Gallery is made of — seven production maps, an Experimental shelf, all five capabilities in one plugin

Research Gallery                          <doxa-maps-spa>          capability 5
├─ Dashboards
│  ├─ Big Picture                         dashboard-plus-grid      capability 4
│  │   ├─ research dashboard              research-dashboard       capability 3
│  │   └─ people-groups grid              people-groups-grid       capability 2
│  ├─ Simple Research                     research-map-plus-grid   capability 4
│  │   ├─ research map                    doxa-research-map        capability 3
│  │   └─ people-groups grid              people-groups-grid       capability 2
│  └─ Regions                             regions-mfe              capability 4
│      ├─ regions list                    regions-list             capability 1
│      └─ region dashboards               region-dashboards        capability 1
├─ Prayer Mobilization
│  ├─ UPG-100 List                        upg-100-mfe              capability 4
│  │   ├─ list                            upg-100-list             capability 1
│  │   └─ poster wall                     poster-wall              capability 1
│  └─ Prayer Progress                     doxa-simple-map          capability 2
├─ Gospel Research
│  ├─ Cities with Internet                connectivity-map         capability 1
│  └─ Gospel Resources                    resources-map            capability 1
└─ Experimental (a folded shelf, filled automatically from manifest.json)
   ├─ prayer walk planner                 prayer-walk-planner      capability 1
   ├─ UPG neighbor                        upg-neighbor             capability 3
   ├─ all people groups                   all-people-groups        capability 1
   ├─ country posters                     country-posters          capability 4
   └─ vision card                         doxa-vision-card         capability 2

Capability 4 — composite: plugins wired together

Nests lower-tier plugins and wires them with props and events. plugin-designs/my-upg-100-list/

List (cap 1, embeddable alone)	Poster wall (cap 1, embeddable alone)

Capability 3 — multi-view: many views, one element

plugin-designs/doxa-research-map/

Capability 2 — presets: one plugin, many maps

One root.vue plus a preset table. plugin-designs/doxa-simple-map/

Prayer	Engagement	Adoption

Capability 1 — single element

One folder, one .vue, one element. plugin-designs/all-people-groups/

Which bundle sits at which tier is generated, not remembered: documentation/reference-capability-exemplars.md.

---

The 5 deployment methods

1. iframe — the prayer map on any site ✅ production

One <iframe> tag, no build step. Each plugin's exact snippet is embed.iframe in manifest.json:

<iframe src="https://YOUR_HOST/doxa-maps/doxa-simple-map/doxa-simple-map/prayer/index.html?utm_source=YOUR_SOURCE"
        width="100%" height="600" style="border:none;border-radius:12px;" allowfullscreen></iframe>

2. Mobile app — UPG-100 on a phone ✅ built

The UPG-100 prayer lists and posters, shipped on their own as a Capacitor app: one poster per row, print options that wrap to fit. bun run check:mobile · bun run phone (needs Android SDK + JDK 17)

3. JavaScript embed — the Research Gallery on dx-life ✅ production

The whole capability-5 app on the dx-life research page, from one <script src> and one element — replacing the separate research map, list and regions dashboards the page used to carry. The exact snippet is embed.script in manifest.json; copy its integrity hash from there, as it changes with every build:

<script>window.MAP_APP_API_URL="https://pray.doxa.life";</script>
<script src="https://YOUR_HOST/doxa-maps/doxa-maps-spa/doxa-maps-spa.js"
        integrity="sha384-…" crossorigin="anonymous"></script>
<doxa-maps-spa profile-config='{"profile":"doxa-maps-spa","tk":"YOUR_MAPBOX_TOKEN","utmSource":"YOUR_SOURCE","assetsBase":"https://YOUR_HOST/doxa-maps/assets"}'></doxa-maps-spa>

4. WordPress / Disciple Tools plugin — 🧪 proof of concept

A shortcode + block plugin in deployment/wordpress/; its contract test passes (bun run check:wp-embed). Proven, not production-ready.

5. Desktop app (Tauri) — 🧪 proof of concept

A desktop binary and .deb build from deployment/src-tauri/ (bun run check:tauri). Proven, not production-ready.

_{WordPress and Tauri marks from Simple Icons (CC0); the trademarks belong to their owners.}

Mapbox token: the dev server bakes one in; built pages take ?tk=pk.…, a pasted token, or a token endpoint. Or skip Mapbox entirely: provider: "maplibre" on any instance renders on MapLibre with no key. Every command and prerequisite: documentation/README-SECTION-3-cli-commands.md.

---

Build it with an agent swarm

Every plugin has one agent responsible for building it, working in its own git worktree. The plugins live together in the Plugin Studio — one repo, one shared library — and one shepherd makes sure every agent is doing its job well. Changes land on main through a merge queue (the model behind GitHub's merge queue and GitLab's merge trains): one at a time, rebased and gated.

# one worktree + one agent per plugin
git worktree add -b regions/work ../dx-maps-regions main
git worktree add -b upg100/work  ../dx-maps-upg100  main

# one dev server per agent, each on its own port
bun x vite --port 5301 --strictPort

# land through the queue: one at a time, rebased, gated
flock /tmp/dx-maps-main.lock sh -c '
  git fetch origin && git rebase origin/main &&
  bun run gates:pre && git push origin HEAD:main'

One agent owns the full build (it wipes the shared output first); everyone else checks their own bundle with BUNDLE=<name> bun x vite build. How to contribute, and the bar for shared code: documentation/CONTRIBUTING.md. Diagram source: delegation-model.svg.

---

The Plugin Studio — ★ where you work

Every plugin in one place, sorted by capability. Pick any plugin to run it live, see what it is composed of, and copy its embed code. Tell your agent which plugins to group, and it composes them into a higher-capability plugin with props, events and a layout — that is how the Research Gallery was built. (The studio is being redesigned; this screenshot tracks it.)

Get it running

You need git, Bun and Node ≥ 18.

git clone https://git.nuxtbase.app/doxa-open/doxa-maps.git
cd doxa-maps
bun install --frozen-lockfile
bun run dev                     # → http://localhost:5173/  is the Plugin Studio

No build needed first — the built tree is committed. To start a plugin, copy plugin-designs/template-bundle/ to plugin-designs/<your-map>/; the studio finds it automatically.

Command	What it does
bun run dev	The Plugin Studio, hot-reloading, at http://localhost:5173
BUNDLE=<name> bun x vite build	Build one bundle only
BUILD_ALLOW=1 bun run build	The full deployable tree in public/doxa-maps/ (~4 min; refuses without the flag, to protect a shared tree)
bun run serve	Serve the built tree at http://localhost:4173
bun run check:settled	Exit 0 = the built tree is safe to measure right now
bun run gates:pre · bun run gates:post	The verification gates
bun run shots	Regenerate these screenshots (ONLY=<name> for one)

---

Repository layout

plugin-designs/   YOUR maps — one folder per plugin, a free zone
library/          the SHARED toolkit (layouts, components, composables) — a high bar
public/doxa-maps/ the build output: the drop-anywhere tree + manifest.json
deployment/       Capacitor · WordPress · Tauri
internal/         the build generator and the gates
documentation/    tutorial · how-to · reference · architecture — start at documentation/README.md

Maps should be open source, run everywhere, and multiply. One build makes each map a self-contained file for your site, your partners' sites and a phone. The Plugin Studio is where you compose them into something bigger.