From 15205d3ce1eb84329fd6490f5e5d951c775b5f7d Mon Sep 17 00:00:00 2001 From: driver Date: Tue, 15 Sep 2026 23:36:34 +0000 Subject: [PATCH] Update README.md --- README.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index d4098ffb8..97154fbf5 100644 --- a/README.md +++ b/README.md @@ -31,16 +31,16 @@ New to this? Read this table first. You do **not** need to memorize it — just | **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](https://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](https://bun.sh) | -| **node modules** | The reusable code packages your project depends on. `bun install` downloads them into `node_modules/`. | [bun.sh/docs](https://bun.sh/docs/cli/install) | -| **Dev server** | A local preview website (`bun run dev`) that updates live as you edit. Yours runs at `http://localhost:5173`. | — | +| **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](https://bun.sh/docs/cli/install) | +| **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**. You commit to learning one. | [vuejs.org](https://vuejs.org) | | **Web component** | A custom HTML tag (like ``) that works on any page, no framework required. Each of your maps becomes one. | [MDN: Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) | -| **iframe** | A safe window that embeds one site inside another. Simple, isolated. | [MDN: iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) | +| **iframe** | A safe window that embeds one site inside another. Simple, isolated. Each map comes with iframe support by default | [MDN: iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/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](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_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](https://developer.mozilla.org/en-US/docs/Glossary/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](https://developer.mozilla.org/en-US/docs/Glossary/CDN) | +| **SPA (single‑page application)** | One page that composes several maps together in a layout — a whole multi-map site from one build. | [MDN: SPA](https://developer.mozilla.org/en-US/docs/Glossary/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](https://developer.mozilla.org/en-US/docs/Glossary/CDN) | | **Minify** | The build shrinks your code into compact, hard‑to‑read (but still working) form — smaller and harder to copy. | [MDN: Minification](https://developer.mozilla.org/en-US/docs/Glossary/Minification) | -| **Capacitor** | Wraps your web app into a real iOS/Android app — **same code, no Swift, no Flutter, no React Native.** | [capacitorjs.com](https://capacitorjs.com) | +| **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.** | [capacitorjs.com](https://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](https://web.dev/articles/lazy-loading) | --- @@ -61,12 +61,12 @@ But then you wanted a second map. And a fifth. And a fiftieth. And here's the wa - 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. +- Each one was fragile, glitchy, and difficult to maintain, and harder to form a community around. **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. +That's what this is. Built for communities of map makers who want to make open source maps that can multiply everywhere. --- @@ -76,9 +76,10 @@ That's what this is. - **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. +- **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. + 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. --- @@ -88,7 +89,7 @@ That's what this is. *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). + 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 @@ -97,9 +98,9 @@ That's what this is. - **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. + that embeds a map picks up the latest version when their cache refreshes. -**One codebase → desktop website · embedded on partner sites · WordPress · mobile app · standalone.** +**One codebase → your own map website · embedded on partner sites · WordPress · mobile app · standalone.** --- @@ -150,7 +151,7 @@ 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. +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) @@ -167,7 +168,7 @@ JavaScript.* They were right. So here's the honest deal before you start: - 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. + 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. @@ -202,7 +203,7 @@ Your map data has to come from somewhere. Common sources: ## 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.** +> 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