doxa-maps — prayer maps that embed everywhere

Bottom line up front. A global prayer movement stalls when there is only one website where people can see the task and sign up — today that plateau sits at roughly 600–1,000 people groups covered. The fix is not a better single website. It is a map that lives on thousands of partner-team websites at once, shows the prayer task clearly, changes as people sign up, and carries a Share button so every team that receives it can pass it on. This bundler builds that map — and every other map you need — as one embeddable file each.

Why embed, not link

One sign-up site is a bottleneck. A map embedded on a partner team's own site multiplies three surfaces at once: the prayer surface (more people see the task), the information surface and the understanding surface. And a team that has the map on its own site treats it as its own — ownership becomes stewardship. Sign-up can still happen in one place; the map does not have to.

What this trains you to be (Training for Trainers)

We borrow the language of Training for Trainers (T4T) — Ying Kai's method, told in T4T: A Discipleship Re-Revolution (Steve Smith with Ying Kai, 2011; trainer resources at t4tonline.org): the goal is never one trained person, but trainers who train trainers. This README trains you to be three things:

1. a map maker — you (with your AI agent) build maps on the shared library in this repo;
2. a map multiplier — every map you build embeds anywhere and carries a Share button;
3. a prayer mobilizer — you run the campaign that multiplies the surface: the map onto the website of every team you know that is trying to multiply disciples among the unreached, and each of them trained to pass it on with the same button — the Playbook.

Everything below is for the people who build the maps. If you only want to run the campaign, jump to the Playbook; the full walkthrough is docs/tutorial.md.

---

What the bundler is — a JAMstack map bundler for vibe coders

Built by a vibe coder, for vibe coders — and for map multipliers and prayer mobilizers who want every people, in every place, prayed for by name.

One build turns every map into a self‑contained web component that embeds anywhere an embed script or URL works, and every map carries the Share button so any team can pass its map to the next team. The seemingly impossible part: the same build also composes all your maps, tables, and dashboards into a single‑page application that runs as a website, installs as a mobile app, and embeds on partner sites piece by piece. Same code, every screen.

One build, same code: the SPA in a desktop browser and on a phone — many maps, one place.

• One repo, one library — every map shares components. Not fifty folders of duplicated spaghetti.
• bun run dev → a live plugin gallery of every map, each with a copy‑paste embed snippet.
• bun run build → every map ships as its own self‑contained embeddable file (script tag or iframe — WordPress included), and the same build feeds the SPA and the mobile app.

You don't write the code. Point your AI agent at the example maps, describe what you want in plain English, and it builds a new one on the shared library.

⚠️ Maps ship without data — being JAMstack (pure JS), they fetch it (like people groups) from an API at runtime (details).

---

Have you ever dreamed of making maps?

Here's the story. Maybe it's yours too.

You got into building software right as AI made it possible for anyone to write code. And you had a vision: make maps — every map you could imagine — to advance the Kingdom of God, so that every people in every place could hear the gospel of Jesus.

So you started. And it worked… for one map. AI is great at writing a single map — a couple thousand lines of code you can embed on a website.

But then you wanted a second map. And a fifth. And a fiftieth. And here's the wall you hit:

• Every new map meant copying the whole thing into a new folder — nothing was reusable.
• Your maps grew past 2,000… 5,000… lines of tangled "spaghetti code."
• You ended up with 50 folders, 50 map projects, scattered across your machine — half of them lost.
• Each one was fragile, glitchy, and difficult to maintain, and harder to form a community around.
• You tried to build the bigger platform — many maps in one app — and the agent got stuck past map one. Somewhere in there, the mobile‑app dream quietly went out the window.

If that's you: you built maps for Jesus. I salute you. Those maps have their place. But you were missing one thing — a framework that lets all your maps live in one place and share reusable pieces.

That's what this is. Built for communities of map makers who want to make open source maps that can multiply everywhere. And the dream you threw out the window? The SPA here runs on your phone by design — same code.

---

Key terms (don't be afraid of these — you can learn each in one search)

New to this? Read this table first. You do not need to memorize it — just know the words exist and where to learn them.

Term	In plain words	Learn more
Vibe coder	Someone who builds with AI writing most of the code. That's who this is for.	—
JAMstack	A way of building where the front end is just JavaScript, APIs, and Markup (HTML/CSS). It runs almost anywhere — including WordPress.	jamstack.org
Bundler	A tool that takes all your code and packs it into a few ready‑to‑ship files. This repo is a bundler for maps.	vite.dev/guide
Build step	The one command (bun run build) that turns your code into those shippable files. Your agent can run it for you.	—
bun	A fast, all‑in‑one replacement for npm (installs packages, runs scripts). We use it here.	bun.sh
node modules	The reusable code packages your project depends on. If you use VUE, and VITE you need Node Modules. It is like installing libraries and dependencies that allow VUE to work. bun install downloads them into your doxa-maps folder on your laptop node_modules/.	bun.sh/docs
Dev server	A local preview website (run this command 'bun run dev' after 'bun install') that updates live as you edit. You run it, it let's you see all the maps in one place so you can give your agents feedback, and see changes almost real time when the agent makes edits. It runs at http://localhost:5173.	—
Vue / React	Popular, well‑supported frameworks for building front ends. This bundler is built on Vue + Vite — commit to learning Vue (if you know React, the concepts transfer).	vuejs.org
Web component	A custom HTML tag (like <doxa-map>) that works on any page, no framework required. Each of your maps becomes one.	MDN: Web Components
iframe	A safe window that embeds one site inside another. Simple, isolated. Each map comes with iframe support by default	MDN: iframe
Shadow DOM	Lets your map's JavaScript run directly inside the host page (not walled off in an iframe) so it can integrate deeply — while keeping its styles from clashing.	MDN: Shadow DOM
SPA (single‑page application)	One page that composes several maps together in a layout — a whole multi-map site from one build.	MDN: SPA
CDN	A URL that serves a file (JavaScript/CSS) to be fetched and run in a browser. When you use Mapbox, you're loading its CDN. Your built maps are served the same way. JAMstack allows these map frontends to run through a CDN, yes they are that modular! Or, you can run them directly in your site, but CDN allows them to embed via iframe onto partner websites easily with a single URL	MDN: CDN
Minify	The build shrinks your code into compact, hard‑to‑read (but still working) form — smaller and harder to copy.	MDN: Minification
Capacitor	Wraps your maps app into a real iOS/Android apps, or make a SPA ('single-page application' see above) by joining multiple maps together into a layout, and bundling that SPA into IOS/Android easily — same code, no Swift, no Flutter, no React Native. (The Android project ships in this repo; iOS scaffolds the same way on a Mac.)	capacitorjs.com
Lazy loading	Only loads each map when it's actually needed, so a page with many maps stays fast.	web.dev: lazy loading

---

What doxa-maps gives you

• One repository for all your maps. Each map is an application profile in app-profiles/<your-map>/.
• A shared library of reusable, parameterized components (library/ — the map, the legend, the controls, the search bar) so your maps stop duplicating code.
• Room for each map's own custom code — because real maps always have something unique.
• Rapid prototyping. Add a .vue app-profile file, rebuild, and it's live. Build hundreds of maps from one library.
• Your agent's happy place. Everything's in one folder, so your AI agent has all the context it needs to build the next map from the examples already here. Give your agent the proper context and it will have what it needs to make new maps. The only limit is our fear of new architecture, we can learn JAMstack, and see the use cases, and grow in a new framework of software design that is appropriate for open source maps that need to embed everywhere.
  • The Great Commission's Maps Everyone needs to work together to fulfill the great commission, and it will not be possible without maps. Allowing map communities to multiply open source maps that can embed onto all partner sites means doxa-maps is built to solve global mobilization problems, not just a map for centralized website.

---

The parts that make you do a backflip

• One build → many embeddable maps. bun run build turns every map into a self‑contained web component and generates a standalone HTML page for each one.
• Embed anywhere. Drop a map on your own site, a partner team's site, or WordPress — via an iframe (safe and isolated) or via shadow DOM (the map's JavaScript runs directly in the page, for deep integration and advanced features).
• Compose maps into a single‑page app. Put several maps into one layout — a whole multi‑map site — and it lazy‑loads each map so it stays fast even when there are many.
• Turn it into a mobile app. The same code runs as an iOS/Android app via Capacitor — no new language to learn. Design it mobile‑friendly right in your browser (inspect element → switch to a phone aspect ratio), then wrap it.
• Your source stays protected. The build minifies your code — it still runs perfectly, but anyone who grabs it off a partner site gets compact, hard‑to‑read output, not your clean source.
• Update once, everywhere. Serve the built maps from a CDN, and when you rebuild, every partner site that embeds a map picks up the latest version when their cache refreshes.

One codebase → your own map website · embedded on partner sites · WordPress · mobile app · standalone.

---

The Playbook — start a prayer movement with this map

The learn‑by‑doing use case this bundler was built for. Five steps, trainable to any team:

1. List your partner teams. Build a spreadsheet of every team you know that is working to multiply disciples among the unreached — their websites, and the contact who can edit each site.
2. Keep the list in a secure, collaborative CRM — not a loose file. That list of teams, contacts, and sites is an attack surface in the wrong hands; protect the people on it. Disciple.Tools is an open‑source, multiplayer CRM built exactly for tracking teams, contacts, and mobilization campaigns — privately.
3. Commission prayer mobilizers. Assign real people to work the list — call, network, and ask each team to put the prayer map on their site and present it to their spiritual family.
4. Embed everywhere. Press the map's Share button: Share Link is the map's own page, Add to Your Website is the embed code — both carry the full URL of whatever host serves your maps (plus a utm_source tag on the generated pages, so every site's traffic is measurable). Verified places a pasted embed works: team websites and WordPress (Custom HTML block), Squarespace (Code block — iframes need a Business or Commerce plan), Wix (Add → Embed → HTML iframe), Google Sites (Insert → Embed → By URL), Notion (/embed + the Share Link), and internal boards with an iframe add-on (e.g. Trello's Card Frames Power-Up). Rule of thumb: anywhere that accepts an HTML snippet or a URL embed, over https.
5. Train the trainer. Teach each team to use the Share button to embed the map — then teach them to train the next team the same way. The movement doesn't hang on one mobilization team: every team that carries the map can multiply it.

The result: one signup flow, a thousand doorways into it — and a map that visibly changes as people commit, so every team watches the task shrink on their own site.

A word before you decide

This architecture is probably different from what you're used to. Different doesn't mean worse — it means it can make your life better and let you build the maps of your dreams.

So be honest with yourself. If you don't have big dreams about map‑making, this product might not be for you — and that's okay. But if you dream of maps that change the world and carry the gospel to places it has never been, you're going to need more than a vibe‑coded map. You'll need a framework that supports far more components than a typical one‑off map. And you'll need a community.

You can't form a community around spaghetti‑coded maps. You can form one around a shared framework with a reusable library — because then people prototype on the same foundation and build something stronger together, where maps never have to be rewritten from scratch. One problem that hinders the Great Commission, is each worker keeps their maps private source, and don't have a shared map framework to build maps on, with reusable map components in a modern framework like VUE with VITE embeddability support. Doxa-maps aims to meet this open source map gap for a global prayer movement which needs more maps, maps, maps!

Requirements — the one small wall (and it's worth it)

Someone once told me: don't reinvent the wheel — use Vue and Vite instead of hand‑rolling vanilla JavaScript. They were right. So here's the honest deal before you start:

1. Commit to learning Vue. This bundler is built on Vue + Vite (React skills transfer — the components you'll touch are Vue). You don't have to master it — but pick one and lean in. (Afraid you can't learn a new architecture? You can. The concepts are one search away — that's what the glossary above is for.)
2. Learn the four basics (your agent can run all of them):
   • bun install — get the dependencies
   • bun run dev — the dev server (live preview)
   • bun run build — the build step (ship it)
   • what node_modules are (the downloaded dependencies)
3. You do not need to write the code. Give your agent access to the example maps in app-profiles/ plus the shared library/, describe your map in plain English, and it builds a new map that reuses the library instead of duplicating spaghetti. The library is for reusable components while the app profiles is for storing custom components that are not reusable, and are specific to that app-profile or map-app. Each map app has custom components that are not reusable and they are not appropriate in the shared library, but if you look at other app-profiles you will see they store their custom components, as well as their main.vue file for the map in the app-profiles folder.

That's the wall. It's small, and everything past it is the maps of your dreams.

---

Quickstart

You need bun installed (bun.lock is committed, so installs are reproducible).

bun install        # download node_modules (one time)

bun run dev        # the plugin gallery: http://localhost:5173 (or the next free port — read the terminal)
                   # an auto-generated SPA of every map, grouped by bundle and composition tier,
                   # each deep-linkable; `bun run smoke:gallery` proves every one of them boots

bun run build      # the build step: every app-profiles/<map>/ becomes
                   # public/doxa-maps/<map>/<map>.js  +  a standalone index.html per map

bun run serve      # preview the BUILT tree (the SPA shell + every embed page)
bun run phone      # build → sync → Android APK on a connected phone (Capacitor)

bun run build writes everything into public/doxa-maps/ — that's your output folder. Copy it wherever your site or CDN serves files (for example, a host repo's public/ directory), and your maps are live.

Embed a map

<!-- 1) the map engine (Mapbox shown here) -->
<link  href="https://api.mapbox.com/mapbox-gl-js/v3.24.0/mapbox-gl.css" rel="stylesheet" />
<script src="https://api.mapbox.com/mapbox-gl-js/v3.24.0/mapbox-gl.js"></script>

<!-- 2) your built map + its custom tag -->
<script src="/doxa-maps/my-map/my-map.js"></script>
<doxa-map profile-config='{"profile":"my-map","tk":"pk.eyJ..."}'></doxa-map>

Prefer not to run JavaScript on the host page? iframe the generated page instead: /doxa-maps/<map>/<profile>/index.html. Both snippets are pre‑generated for every map in public/doxa-maps/manifest.json.

---

The data caveat

Read this so nothing surprises you: the maps ship without their data. Because they're JAMstack (pure JavaScript), each map fetches its data — like people‑group information — from an API at runtime. That's what keeps them embeddable everywhere.

Your map data has to come from somewhere. Common sources:

• Joshua Project
• PeopleGroups.org
• A project API. doxa-maps was originally built to serve DX, which runs its own people‑group API (https://pray.doxa.life) covering the unreached people groups these maps were made to pray over. The data source, the map token, and even the map engine (Mapbox ↔ MapLibre) are runtime settings — change them with no rebuild.

---

Docs

Read this	When
docs/why.md	2 min — the problem, the idea, one diagram
docs/tutorial.md	build your first map, step by step (great to hand to your agent)
docs/how-to.md	task recipes (embed, data, mobile)
layouts/README.md	the SPA composition machinery (many maps → one app)
docs/architecture/	the deep end — embeddability, app-wrappers, file map

---

A note from the developer

Bottom line: maps should be open source, they should run everywhere, and no movement of God has ever moved without maps.

You found some really cool maps on the internet, didn't you? On discipleship sites, maybe — maps that inspired you, that made you want to build your own. But the code wasn't available. Or if it was, it wasn't written to run on WordPress, or on your own site, or across your partner teams' websites. It wasn't simple. It wasn't modular. It didn't work the way you needed it to.

That was me too. That's why I built this framework. I love maps — I'm going to build maps until the day I die — because I want to see the Kingdom of God advance to the places it has never been, and I long to see a global movement of map‑makers multiplying maps everywhere.

I want the Great Commission fulfilled in my lifetime, and there is no global movement without map‑making. Look at Scripture: Jerusalem, Judea, Samaria, and the ends of the earth — the book of Acts is a map, all the way to Rome. Where do you find a movement of God without maps at its white‑hot center? Nowhere. So why would we lock our maps away and make them closed source? Why should the power to make a map sit in the hands of a few who never release their code?

It shouldn't. This was built to be open source, to serve movements of God — so the maps can multiply to every device: WordPress, your own site, an embeddable script on Squarespace, mobile, anywhere an embed can run. If we want to put map‑making into the hands of every disciple, we need a framework that lets the maps go, lets them be reusable, and lets a community build them together.

If you have a vision to reach the globe but you've been stuck vibe‑coding an entire platform alone — with no open‑source foundation that runs on your site and your partners' sites — that gap isn't your fault, and you don't have to stay there. You can escape it by adopting a framework that has already been where you are.

Come build the maps of your dreams. Let's reach every people, in every place.