From ca70d5d9e475b6c7e3c764e5b7be4280c2ec7b9c Mon Sep 17 00:00:00 2001 From: cyclez <54079958+cyclez@users.noreply.github.com> Date: Wed, 25 Mar 2026 22:42:46 +0100 Subject: [PATCH] docs: add emergency seam map for upstream reuse --- docs/emergency/README.md | 1 + docs/emergency/SEAM_MAP.md | 195 +++++++++++++++++++++++++++++++++++++ 2 files changed, 196 insertions(+) create mode 100644 docs/emergency/SEAM_MAP.md diff --git a/docs/emergency/README.md b/docs/emergency/README.md index 9da42c8..f53573f 100644 --- a/docs/emergency/README.md +++ b/docs/emergency/README.md @@ -21,6 +21,7 @@ The profile is designed for a dedicated Android device running Ubuntu/Linux wher - [Architecture](./ARCHITECTURE.md) - [Local API](./LOCAL_API.md) +- [Seam Map](./SEAM_MAP.md) - [Bootstrap Prompt](./BOOTSTRAP_PROMPT.md) ## Intended use diff --git a/docs/emergency/SEAM_MAP.md b/docs/emergency/SEAM_MAP.md new file mode 100644 index 0000000..1b28e87 --- /dev/null +++ b/docs/emergency/SEAM_MAP.md @@ -0,0 +1,195 @@ +# Emergency Seam Map + +## Purpose + +This note identifies the best upstream seams to reuse in the emergency downstream fork and the areas that should remain isolated in v1. + +The goal is to keep the delta against Project N.O.M.A.D. small while moving toward a hard-offline, device-first runtime. + +## Strong seams to reuse first + +### 1. Collections and manifest contracts + +This is the strongest reuse seam in the current upstream tree. + +Relevant upstream files: + +- `collections/kiwix-categories.json` +- `collections/maps.json` +- `collections/wikipedia.json` +- `admin/types/collections.ts` +- `admin/app/validators/curated_collections.ts` +- `admin/app/services/collection_manifest_service.ts` +- `admin/app/models/collection_manifest.ts` + +Why it is strong: + +- the resource contract is explicit and already versioned via `spec_version` +- upstream already validates the manifest schema +- status computation is already separated from UI concerns +- the same seam covers ZIM, maps, and curated Wikipedia content + +Emergency fork guidance: + +- preserve these schemas as long as possible +- treat them as the canonical source selection layer +- add emergency-specific metadata only through additive fields or adapters + +### 2. Installed resource registry + +Relevant upstream files: + +- `admin/app/models/installed_resource.ts` +- `admin/app/services/collection_manifest_service.ts` +- `admin/app/services/collection_update_service.ts` + +Why it is useful: + +- upstream already tracks `resource_id`, `resource_type`, `version`, `url`, `file_path`, and install time +- this is close to the emergency fork's need for local package/install state + +Emergency fork guidance: + +- reuse the conceptual shape +- keep an adapter boundary because the emergency runtime will likely want extra sync state and stronger local-only semantics + +### 3. Maps pipeline + +Relevant upstream files: + +- `collections/maps.json` +- `admin/app/services/map_service.ts` +- `admin/app/controllers/maps_controller.ts` +- `admin/start/routes.ts` + +Why it is strong: + +- map packs are already treated as a distinct asset class +- upstream already has PMTiles-specific download and asset handling +- there is already a collection-based install flow for map groups + +Emergency fork guidance: + +- reuse the collection metadata and PMTiles handling ideas +- keep map storage and install semantics compatible where practical +- isolate browser/admin-specific delivery details behind adapters + +### 4. Download job abstraction + +Relevant upstream files: + +- `admin/app/jobs/run_download_job.ts` +- `admin/app/utils/downloads.ts` +- `admin/app/services/queue_service.ts` + +Why it matters: + +- upstream already models resumable background downloads with retry and deduplication by URL +- this is close to the emergency fork's bounded ingest path + +Emergency fork guidance: + +- keep the download lifecycle shape +- do not couple the emergency runtime directly to BullMQ, Docker, or embedding callbacks +- wrap this seam behind a simpler emergency sync job interface + +## Medium-strength seams to adapt, not adopt whole + +### 5. Route and capability separation + +Relevant upstream file: + +- `admin/start/routes.ts` + +What is reusable: + +- upstream capability boundaries are clear: maps, docs, downloads, settings, system, ollama, rag, zim + +What to do in the emergency fork: + +- reuse the capability partitioning idea +- do not mirror the entire route tree +- build a smaller loopback API around `status`, `mode`, `sync`, `search`, `documents`, `maps`, and `sources` + +### 6. Collection update flow + +Relevant upstream file: + +- `admin/app/services/collection_update_service.ts` + +What is reusable: + +- update-check request shape +- version comparison flow +- dispatch to resource-specific download handling + +Why it is only medium strength: + +- it assumes a remote Nomad API and current server-side orchestration choices +- the emergency fork needs stricter `OFF` behavior and one-shot exception semantics + +## Seams to isolate or avoid in v1 + +### 7. RAG and embedding runtime + +Relevant upstream file: + +- `admin/app/services/rag_service.ts` + +Why to isolate: + +- it pulls in Qdrant, Ollama, OCR, PDF pipelines, and embedding behavior +- this is not aligned with the emergency v1 requirement of deterministic local search via SQLite FTS + +Rule: + +- reuse ideas about ingestion boundaries, not the runtime dependency stack + +### 8. Ollama and model-management services + +Relevant upstream area: + +- `admin/app/services/ollama_service.ts` +- `admin/app/controllers/ollama_controller.ts` + +Why to isolate: + +- this is optional future capability, not part of the emergency core + +### 9. Docker and system-orchestration assumptions + +Relevant upstream area: + +- `admin/app/services/docker_service.ts` +- `install/` + +Why to isolate: + +- the emergency fork is device-first and should not depend on Docker as the core runtime model + +## Recommended first extraction order + +1. Collections and validators +2. Installed resource state and local package metadata +3. Maps metadata and PMTiles install flow +4. Bounded download abstraction +5. Loopback-only emergency API around those seams + +## Rule of thumb + +If a piece of upstream code helps define: + +- what content exists +- how it is versioned +- how it is downloaded +- how it is stored locally + +then it is probably a good seam. + +If a piece of upstream code primarily exists to: + +- manage containers +- power chat or embeddings +- expose server/admin UX assumptions + +then it should stay out of the emergency v1 core.