Merge pull request #2 from adab-tech/build/mapping-voices

Build Mapping Voices: an interactive atlas of oral-history archives

Author: adab-tech

.github/workflows/deploy-pages.yml

@@ -0,0 +1,55 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  # Allow manually triggering a deployment from the Actions tab.
+  workflow_dispatch:
+
+# Allow one concurrent deployment; skip runs queued behind an already-running one.
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Validate data/collections.json
+        run: node scripts/validate-data.mjs
+
+  deploy:
+    needs: validate
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # This is a plain static site (no build step) — publish the repo root.
+          path: .
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -1,30 +1,93 @@
 # Mapping Voices
 
-Digital humanities project for analyzing and visualizing mapped voice data.
+Mapping Voices is an interactive atlas of oral-history and voice-testimony
+archives. It's a single map, filterable by country, theme, language, and
+decade, that puts a pin on every collection in its dataset: click a pin (or
+use the filters) and you get a plain-language summary plus a link straight
+through to the real archive holding that collection.
 
-[![Portfolio](https://img.shields.io/badge/Adamu_Abubakar-adamu.tech-0f766e?style=flat-square)](https://adamu.tech)
-[![DH](https://img.shields.io/badge/Focus-Digital_Humanities-4f46e5?style=flat-square)](https://adamu.tech)
+It exists because oral history is scattered. National sound archives,
+university folklore centers, UNESCO-listed oral-tradition programs,
+grassroots memory projects, and things like StoryCorps or the Genocide
+Archive of Rwanda each publish their own holdings on their own site, with no
+shared, geographic way to see what's out there across all of them at once.
+This project is a single entry point for browsing that landscape spatially —
+built for digital humanities researchers, oral historians, students, and
+anyone else curious about oral history and voice-testimony archives, and
+useful today because nothing like it currently exists. It's a standalone
+static web app, deployed on GitHub Pages, with no backend and no build step.
 
----
+## Running it locally
 
-## Overview
+There's no build step — it's plain HTML/CSS/JS served over `fetch()`, so any
+static file server works. From the repo root:
 
-Mapping Voices supports exploratory analysis of voice-related humanities datasets with an accessible web front end.
+```bash
+# Python (already on most systems)
+python3 -m http.server 8080
+
+# or Node, if you have it
+npx http-server -p 8080
+
+# or PHP
+php -S localhost:8080
+```
+
+Then open `http://localhost:8080`. Opening `index.html` directly via
+`file://` won't work — the app fetches `data/collections.json` at runtime,
+and browsers block `fetch()` against `file://` URLs.
+
+## The seed dataset
 
-## Features
+`data/collections.json` holds the map's data: about 30 entries covering
+real, publicly documented oral-history and voice-testimony collections, with
+real institutions and a real, working link to each collection's own public
+page. No fictional archives, testimonies, or recordings are included — if an
+entry couldn't be verified as real, it isn't here. The set deliberately
+spans every inhabited continent, with particular attention to Niger and the
+wider Sahel/West Africa region (Niger's CELHTO and IRSH, Mali's Sunjata-epic
+field recordings, Guinea's Sosso-Bala griot tradition, Nigeria's Ifa corpus,
+Benin/Nigeria/Togo's Gelede heritage, Senegal's IFAN sound archives, Ghana's
+Nketia Archives), since that region is under-represented in most general
+oral-history tool demos and this project grew out of Hausa/Sahel-region
+digital humanities research.
 
-- Interactive maps and narrative views
-- Static, deployable HTML/JS assets
-- Research-oriented presentation layer
+**This is a curated, illustrative starting set — not an exhaustive index.**
+There are hundreds of oral-history and voice-archive collections worldwide
+that aren't in here yet. See `data/schema-notes.md` for the full field
+reference and the exact steps for adding a new entry (in short: confirm it's
+real, add an object matching the schema, run
+`node scripts/validate-data.mjs`, and fix anything it flags before opening a
+PR).
 
-## Quick start
+## Validating the data
 
 ```bash
-git clone https://github.com/adab-tech/mapping.git
-cd mapping
-# Serve locally, e.g. npx http-server -p 8080
+node scripts/validate-data.mjs
 ```
 
-## Author
+Zero dependencies — plain Node built-ins only, no `npm install` needed. It
+checks that every entry has its required fields, that `lat`/`lng` are real
+coordinates, that every `id` is unique, that `url` is well-formed, and that
+array fields aren't empty, and exits non-zero with a specific message per
+problem found. The same check runs in CI on every push, via
+`.github/workflows/deploy-pages.yml`.
 
-**Adamu Abubakar** · [adamu.tech](https://adamu.tech) · [contact@adamu.tech](mailto:contact@adamu.tech)
+## Deployment
+
+Pushing to `main` runs `.github/workflows/deploy-pages.yml`, which validates
+`data/collections.json` and then publishes the repository root to GitHub
+Pages via `actions/upload-pages-artifact` and `actions/deploy-pages`. No
+build step is involved.
+
+## Project layout
+
+```
+index.html                       entry point
+css/style.css                    styles
+js/app.js                        map + filtering logic
+data/collections.json            the seed dataset (see above)
+data/schema-notes.md             schema reference + how to add an entry
+scripts/validate-data.mjs        zero-dependency data validator
+.github/workflows/deploy-pages.yml   GitHub Pages deployment
+```

SPEC.md

@@ -0,0 +1,95 @@
+# Mapping Voices — build spec
+
+## What this is
+A static, client-side web app (no backend, no build step, deployable via GitHub Pages)
+that lets people explore oral-history / voice-testimony collections on an interactive
+map — filterable by country, theme, language, and decade.
+
+## The 5 Ws (why this exists)
+- **Who**: digital humanities researchers, oral historians, students, and the public
+  interested in oral history and voice-testimony archives.
+- **What**: an interactive atlas — a world map with pins for real, publicly documented
+  oral-history/voice-archive collections; click a pin (or use the filters) to see a
+  summary and a link to the actual source archive.
+- **When**: now — no tool like this exists in this account, and it directly serves
+  active digital-humanities/oral-history research interests.
+- **Where**: a standalone static web app, deployed on GitHub Pages.
+- **Why**: oral history and voice-testimony collections are scattered across dozens of
+  institutional archives with no shared, geographic way to browse what exists — this
+  gives that a single entry point.
+
+## Data honesty rule (important)
+The seed dataset must describe **real, publicly documented oral-history/voice-archive
+collections** (e.g. national sound archives, university oral history projects, UNESCO-
+listed oral tradition collections, StoryCorps, etc.) with accurate metadata and a real
+link to the actual collection/archive page. Do not invent fictional testimonies,
+recordings, or archives. It's a *seed/demo dataset* meant to make the tool immediately
+useful and honest, not an exhaustive index — the README must say so explicitly and
+explain how to add more entries.
+
+## Data schema (`data/collections.json`)
+A JSON array of objects, each shape:
+```json
+{
+  "id": "string, kebab-case, unique",
+  "title": "string — the collection's real name",
+  "archive": "string — the holding institution's real name",
+  "country": "string — ISO-ish common name, e.g. 'Niger', 'United States'",
+  "lat": "number",
+  "lng": "number",
+  "languages": ["array of strings, e.g. ['Hausa', 'French']"],
+  "themes": ["array of strings, e.g. ['migration', 'oral tradition', 'women's history']"],
+  "decade_start": "number, e.g. 1990",
+  "decade_end": "number or null if ongoing",
+  "summary": "1-3 sentences, plain language, on what the collection actually contains",
+  "url": "string — a real, working URL to the collection or archive's public page"
+}
+```
+Aim for ~25-30 entries with real geographic and thematic spread — don't cluster
+everything in one region. Include several African/Sahel-region entries (Niger and
+neighboring countries) alongside collections from other continents, since that region
+is currently under-represented in most general "oral history" tool demos.
+
+## Frontend contract
+The frontend reads `data/collections.json` via `fetch('data/collections.json')` — a
+plain relative path, no build step, works both locally (via any static server) and on
+GitHub Pages. Do not hardcode the dataset into the JS/HTML.
+
+## File layout (fixed — do not deviate, this is how the two build tracks stay non-conflicting)
+```
+index.html
+css/style.css
+js/app.js
+data/collections.json
+data/schema-notes.md      (short doc: how to add a new entry)
+.github/workflows/deploy-pages.yml
+README.md
+scripts/validate-data.mjs (Node, zero-dependency, checks collections.json against the schema)
+```
+
+## Design direction
+Editorial, atlas-like — not a generic SaaS dashboard. Think: a printed atlas or a
+research archive's reading room, rendered for the web. A serif display face for
+titles, a neutral sans for UI chrome. Muted, paper-like background tones (not stark
+white, not dark-mode-first) with one confident accent color for map pins/active
+states. Real typographic hierarchy. The map is the hero — everything else (filters,
+detail panel) supports it without competing with it.
+
+## Map library
+Use Leaflet.js loaded from a CDN (no API key required, unlike Google Maps) with the
+OpenStreetMap tile layer (free, no key, attribution required per their terms — include
+it, it's a one-line requirement).
+
+## Accessibility & responsiveness
+- Filters and the detail panel must be fully keyboard-operable.
+- Map pins need accessible labels (not just visual markers).
+- Must work down to a 375px-wide mobile viewport: map on top, filters/detail panel
+  stack below or slide in as a drawer — your call on the exact pattern, but no
+  horizontal overflow at any width.
+
+## Deployment
+`.github/workflows/deploy-pages.yml` — a GitHub Actions workflow using
+`actions/upload-pages-artifact` + `actions/deploy-pages` to publish the repo root
+(or a `/docs` folder if you prefer — pick one and be consistent with the file layout
+above) to GitHub Pages on every push to `main`. No build step needed since this is
+plain HTML/CSS/JS.