doxa-maps — one build, maps that embed everywhere

A Vite bundler that turns each map into a self-contained web component. One bun run build produces a doxa-maps/ folder you drop on any host — iframe it, script-embed it, ship it as a mobile app, or open the whole thing as one SPA. Same code, every screen.

This README is a show, don't tell index. Skim the three tables, then jump to the section you need.

---

Index

The 5 plugin (app) types — from simplest to full app

#	Capability	What it is	Example plugin	Section
1	Single element	One folder → one bundle → one custom element. The lightest tier.	doxa-vision-card	§1
2	Preset element (prop-table)	ONE root.vue rendered N ways by preset props — one plugin, many maps.	doxa-simple-map (prayer · engagement · adoption)	§1
3	Monolithic / multi-view	A whole research map, all in one root.vue.	doxa-research-map	§1
4	Composite element (nested-element SPA)	A composite element that nests other elements and wires them via props/events.	my-upg-100-list	§1
5	App shell (nested-SPA)	The full doxa-maps app — every plugin in one deep-linkable page.	the doxa-maps SPA	§1

The 5 deployment methods

#	Method	Status	Section
1	iframe embed on any site	required	§2
2	Mobile app (Android / Capacitor)	required	§2
3	Direct-JS / research dashboard (props + events + SRI)	required	§2
4	WordPress (same artifacts, Custom HTML block)	deferred POC	§3
5	Desktop (Tauri)	deferred POC	§3

CLI commands + what to install

Install Bun once, then:

bun install        # download node_modules (one time)
bun run dev        # live plugin gallery at http://localhost:5173
bun run build      # build every plugin-designs/<map>/ → public/doxa-maps/
bun run serve      # preview the built tree
bun run phone      # build → Capacitor → Android APK on a connected device

The full command matrix (per deploy method, with prereqs like the Android SDK / JDK for mobile) lives in §3 → docs/README-SECTION-3-cli-commands.md.

The data caveat: maps ship without data. Being JAMstack, each fetches its people-group data from an API at runtime, and its Mapbox token from a token endpoint (never baked into the bundle). That is what keeps them embeddable everywhere. See docs/how-to.md.

---

1. Plugin types — one screenshot each

Every image below is a real map from this repo's bun run build output (public/doxa-maps/), captured in a headless browser.

CAP 1 — Single element

One folder → one bundle → one custom element. The lightest tier: plugin-designs/doxa-vision-card/. No map engine, mounts instantly — a self-contained "mission vision card."

CAP 2 — Preset element (prop-table)

One root.vue, many maps. plugin-designs/doxa-simple-map/ is a single parameterized profile. A preset prop-table (simple-map.instances.json) renders it three ways — prayer, engagement, adoption — each a standalone embeddable page. Same code, three maps.

Prayer	Engagement	Adoption

All three come from the same doxa-simple-map plugin-design folder — differentiated only by preset props.

CAP 3 — Monolithic research map

A whole research map, all from one root.vue. plugin-designs/doxa-research-map/ — the monolithic tier.

CAP 4 — Composite element

A composite element that nests lower-tier elements and wires them via props/events. plugin-designs/my-upg-100-list/ — the UPG-100 list plugin. The composite (upg-100-mfe) plus its list pages:

Composite element (upg-100-mfe)	List — page 1	List — page 2

CAP 5 — App shell / the doxa-maps app

The top tier: every plugin in one deep-linkable single-page app — public/index.html, generated by the build. A vertical-tab sidebar groups every plugin by capability (CAP 5 → 1); clicking a row mounts that plugin. This same SPA is the Capacitor mobile-app entry (see deploy 2).

---

2. Deployment methods — one screenshot each

The exact commands + install prereqs for each are in §3. These shots show what each method looks like live.

Deploy 1 — iframe embed

The simplest. One <iframe> line drops a map into an "embed section" on any partner site — no build step on their site. Below: the prayer map running in an iframe inside a church's missions page.

Deploy 2 — mobile app

Same code, native app. bun run phone wraps the SPA into an Android app via Capacitor. Below: the doxa-maps SPA at a phone viewport — the exact web output that cap:sync copies into the APK.

Deploy 3 — research dashboard (direct-JS)

Props + events + SRI. plugin-designs/research-dashboard/ embeds via a direct <script src> (with a Subresource-Integrity hash) so the map talks to the surrounding page — a coordinated-views dashboard where the map, the facet rail, and the people-groups table brush-and-link over one store.

---

3. CLI commands + installs (per deploy method)

The complete, copy-paste command matrix — every deploy method mapped to its install prereqs and exact commands, grounded in this branch's package.json — lives in its own doc:

→ docs/README-SECTION-3-cli-commands.md

Quick reference:

#	Deploy method	Install first	Command(s)
1	iframe embed	Bun	bun install → bun run build → bun run serve (or drop public/doxa-maps/ on any host)
2	Mobile (Android)	Bun · Android SDK + adb · JDK 17 · Capacitor (devDep)	bun run phone
3	Direct-JS / dashboard	Bun	bun run build, then paste the <script src> + integrity snippet from manifest.json
4	WordPress	Bun	bun run build, then paste the iframe/script snippet into a Custom HTML block (deferred POC)
5	Desktop (Tauri)	Rust + Tauri CLI (not yet scaffolded)	deferred POC

Every build writes public/doxa-maps/manifest.json — a machine-readable index carrying the ready-to-paste iframe and <script src> + SRI embed snippet for every map.

---

More docs

Read this	When
docs/README-SECTION-3-cli-commands.md	the full per-method CLI + install matrix
docs/why.md	2 min — the problem, the idea, one diagram
docs/tutorial.md	build your first map, step by step
docs/how-to.md	task recipes (embed, data, mobile)
docs/README-longform.md	the original story-first README (the "why maps" manifesto)
docs/architecture/	the deep end — embeddability, app-wrappers, file map

---

Bottom line: maps should be open source, run everywhere, and multiply. This bundler makes each map a self-contained file that embeds on your site, your partners' sites, WordPress, and mobile — from one build.