d1fc658de4
Some checks are pending
build-gate / build (push) Waiting to run
- The five capabilities each lead with a current screenshot; the Research Gallery's composition tree folds into a <details> block. - Deployment: (1) the prayer map in a host page's iframe, (2) the Simple Research dashboard as the phone app, (3) the whole Research Gallery JS-embedded on dx-life's research page. WordPress/Disciple Tools and Tauri are stated as proven proofs of concept, not production-ready. - The Plugin Studio closes the README with its current screenshot, the four-command start and the command table. - 4,151 -> 1,330 words. Every image retaken against the current build. - readme-shots: deploy2 shoots research-map-plus-grid at phone size; deploy3 shoots a running dx-life (DXLIFE_URL=...), skipped when it is not set; an http(s) path is used as-is. Retired four images nothing shows any more.
211 lines
10 KiB
Markdown
211 lines
10 KiB
Markdown
# 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](#the-5-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](#capability-5--app-shell-the-research-gallery) · `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` |
|
||
| **Many agents, one green `main`** | [agent swarm](#build-it-with-an-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/`
|
||
|
||
|
||
|
||
<details>
|
||
<summary><b>What the Research Gallery is made of — all five capabilities in one plugin</b></summary>
|
||
|
||
```text
|
||
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 every other bundle, discovered automatically
|
||
```
|
||
|
||
</details>
|
||
|
||
### 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](./documentation/reference-capability-exemplars.md).
|
||
|
||
---
|
||
|
||
## The 5 deployment methods
|
||
|
||
### 1. iframe — the prayer map on any site ✅ production
|
||
|
||
One `<iframe>` tag, no build step. Copy the `embed.iframe` snippet from `manifest.json`.
|
||
|
||
|
||
|
||
### 2. Mobile app — Simple Research on a phone ✅ built
|
||
|
||
The Simple Research dashboard (research map + people-groups grid), shipped on its own as a
|
||
Capacitor app. `bun run check:mobile` · `bun run phone` (needs Android SDK + JDK 17)
|
||
|
||
<p align="center"><img src="documentation/readme-images/deploy2-mobile-simple-research.png" alt="Method 2 — the Simple Research dashboard at phone size" width="320"></p>
|
||
|
||
### 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. Copy the
|
||
`embed.script` snippet (SRI-pinned) from `manifest.json`.
|
||
|
||
|
||
|
||
### 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.
|
||
|
||
> **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](./documentation/README-SECTION-3-cli-commands.md).
|
||
|
||
---
|
||
|
||
## Build it with an agent swarm
|
||
|
||
Trunk-based development with a **merge queue** — the model behind GitHub's merge queue and GitLab's
|
||
merge trains. Many agents build in parallel, each in its own worktree; changes land on `main` one
|
||
at a time, rebased and gated, so `main` stays green.
|
||
|
||
|
||
|
||
```bash
|
||
# 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`. A **maintainer** reviews what lands and keeps shared
|
||
code shared. Agents joining this repo: read [AGENT-BRIEF.md](./AGENT-BRIEF.md).
|
||
Diagram source: [`delegation-model.svg`](./documentation/readme-images/src/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](https://bun.sh)** and **Node ≥ 18**.
|
||
|
||
```bash
|
||
git clone https://git.nuxtbase.app/doxa-life/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
|
||
|
||
```text
|
||
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.
|