doxa-maps/README.md

doxa-maps — a JAMstack map bundler for vibe coders

Built by a vibe coder, for vibe coders. If you use AI to write your code and you dream of making maps to reach your city — your nation — every people group — for Jesus, this is for you.

---

Bottom line up front

doxa-maps is one repository that holds all your maps and turns them into embeddable apps with a single command.

• One folder for every map. Not 50 folders scattered across your laptop — one repo, one shared library.
• One command to preview: bun run dev → a live playground showing every map in one place, each with a copy‑paste embed snippet.
• One command to ship: bun run build → every map comes out as a self‑contained file you can drop onto any website (your site, a partner church's site, WordPress), compose into a single‑page app, or wrap into a mobile app — from the same code.

You don't have to write the code yourself. Point your AI agent at the example maps in this repo, describe the map you want in plain English, and it builds a new one that reuses the shared library.

⚠️ These maps do not come with their data. They're JAMstack (pure JavaScript), so they fetch their data — like people groups — from an API at runtime. See The data caveat below.

---

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. bun install downloads them into node_modules/.	bun.sh/docs
Dev server	A local preview website (bun run dev) that updates live as you edit. Yours runs at http://localhost:5173.	—
Vue / React	Popular, well‑supported frameworks for building front ends. This bundler is built on Vue + Vite. You commit to learning one.	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.	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 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.	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 web app into a real iOS/Android app — same code, no Swift, no Flutter, no React Native.	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

---

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 impossible to maintain.

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.

---

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 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.

---

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 church'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 power 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 on refresh.

One codebase → desktop website · embedded on partner sites · WordPress · mobile app · standalone.

---

Quickstart

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

bun install        # download node_modules (one time)

bun run dev        # the playground: http://localhost:5173
                   # every map, clickable, with a copy-paste embed snippet for each

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 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.

---

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.

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 or React. This bundler is built on Vue + Vite and supports both patterns. 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.

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

---

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)

---

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 them.

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 churches' 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.

License

Open source. We want this in the hands of every map‑maker on earth — because we want the whole earth to hear the gospel of Jesus. Make all the maps of your dreams. Reach your city. Reach every people, in every place.