TribeFinder Documentation Pack

Version: 1.0 (Developer & User Docs)
Maintainer: Joel Southall (Great Lynx Designs)
Repo: https://github.com/Vexmage/tribe-finder-react
Audience: Developers • Admins/Content Editors • End Users

---

1) Overview (Developer‑Facing)

TribeFinder is a React single-page application (CRA) that helps users locate the nearest tribal offices using a static GeoJSON dataset rendered on Google Maps.

Core features

• Finds the 5 nearest tribal offices based on user’s location (or manual entry)

• Map + list view with synchronized selection

• Responsive UI styled with Bootstrap

• Static dataset (GeoJSON) loaded from /public/

Stack

• React 18 (create-react-app)

• React Router DOM 7 for page navigation

• Bootstrap 5 for styling

• Google Maps JavaScript API for mapping

• Express + MySQL2 (server.js) present but optional/experimental

---

2) Architecture

┌─────────────────────────────┐
│ App (App.js) │
├─────────────┬───────────────┤
│ Navbar.js │ Footer.js │
├─────────────┼───────────────┤
│ Pages: Home, About │ (src/pages/)
├─────────────┼───────────────┤
│ Components: │
│ • Map.js – Map rendering │
│ • TribeInfo.js – Office card│
│ • ZipForm.js – Input form │
├─────────────────────────────┤
│ Utils: │
│ • apiCall.js – data fetch │
│ • googleMaps.js – init/maps │
├─────────────────────────────┤
│ Public data: │
│ • TribalLeadership_Directory_3002994166247985726.geojson │
│ • images/ assets │
└─────────────────────────────┘

---

3) Setup & Local Development

Prerequisites

• Node.js (≥ 18.x)

• npm (ships with Node)

• Google Maps JavaScript API key

Environment Variables

Create .env.local:

REACT_APP_GOOGLE_MAPS_API_KEY=YOUR_KEY_HERE
REACT_APP_DEFAULT_CENTER=44.0521,-123.0868
REACT_APP_DEFAULT_ZOOM=5

Install & Run

# clone
git clone https://github.com/Vexmage/tribe-finder-react.git
cd tribe-finder-react

# install deps
npm install

# start dev server
npm start

Runs at http://localhost:3000/ by default.

Build

npm run build

Outputs production build into /build.

---

4) Data Model & Sources

Data Format (GeoJSON)

Stored in /public/tribal-leaders-json.json

{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"tribe": "Example Tribe",
"office": "Enrollment Office",
"address": "123 River Rd, City, ST",
"phone": "+1-555-123-4567",
"website": "https://example.org"
},
"geometry": { "type": "Point", "coordinates": [-123.0868, 44.0521] }
}
]
}

Notes

• Coordinates in [longitude, latitude]

• Fields may include tribe, office, address, phone, website, hours

---

5) Core Logic

• Distance calculation via Haversine formula in googleMaps.js

• Data loaded by apiCall.js from /public/TribalLeadership_Directory_3002994166247985726.geojson

• Map component initializes Google Maps API and drops markers

• Selecting a list item highlights the marker and recenters map

---

6) UI/UX Conventions

• Bootstrap 5 used for grid + responsive design

• Navbar links: Home, About

• Cards display office info (address, phone, website)

• Simple form (ZipForm.js) to allow manual search or location input

• Images (e.g., compass, fourdirections.png) used for visual branding

---

7) Deployment

• Built with npm run build

• Can deploy to Netlify, Vercel, or any static host

• For GitHub Pages: update homepage field in package.json

Server.js (Express + MySQL2) is included but not required for static hosting. It can be used to serve dynamic data if expanded later.

---

8) End‑User Guide

What TribeFinder Does

• Finds tribal offices near your location or a manually entered city/ZIP

How to Use

1. Open the app URL (e.g., Netlify/Vercel deployment)

2. Click Allow for location access OR enter a ZIP code

3. View the nearest 5 results on the map + list

4. Click a result for office details and links

Accessibility

• Tab through form and list

• Contrast and font-size inherit from system/Bootstrap defaults

---

9) Admin / Content Guide

Updating Data

1. Open /public/TribalLeadership_Directory_3002994166247985726.geojson

2. Add/update office data in valid GeoJSON format

3. Validate with a linter (e.g., geojson.io)

4. Save + redeploy

Checklist:

• ✅ Coordinates in correct order

• ✅ Verified addresses/phone numbers

• ✅ Valid JSON structure

---

10) Release Notes

## [0.1.0] - Initial prototype
- React SPA with map + list
- Bootstrap responsive UI
- GeoJSON static dataset
- Location search (geolocation + ZIP form)

---

11) Troubleshooting

Symptom	Likely Cause	Fix
Map not loading	API key invalid	Check .env.local and Google Cloud restrictions
Blank list	tribal-leaders-json.json missing	Confirm file path and format
Geolocation denied	User blocked location access	Use ZIP form instead
Build fails	Node version mismatch	Use Node 18+

---

12) Credits

• Data sources: DOI datasets + manual tribal office verification

• Maintainer: Joel Southall (Great Lynx Designs)