3HO Summer Solstice Sadhana 2026 PWA

Offline-first mobile app (PWA + native iOS/Android via Capacitor) for the 3HO Summer Solstice Sadhana 2026 festival at Ram Das Puri, near Española, New Mexico (June 19–27, 2026).

It replaces the printed booklet with a searchable program, local favorites and a personal agenda, teacher profiles, an offline info hub, and a zoomable camp map — all working on the device once installed, with no signal required. Offline is the product: every feature degrades gracefully with no connectivity, and the app is fully usable logged out.

The app is evolving into a backend-connected, multi-event native app (see docs/ROADMAP.md). The backend is WordPress + MySQL on 3ho.org (the 3ho-solstice-app plugin lives in the separate 3ho.org repository).

What the app does today

• Program — 125+ activities with day strip, search, quick category select, and advanced filters (multi-select categories, time-of-day presets, custom hour range). Detail page per activity.
• Favorites & My Agenda — heart toggle on program cards, detail pages, and teacher views; stored locally in IndexedDB (Dexie). On the native app, a reminder fires 15 minutes before each favorited session.
• Teachers — directory with photos, full profiles (sessions by day, bio when available), and a quick-view modal from program cards.
• Info Hub — offline reference content generated from the booklet.
• Camp map — app-style pan/scroll with internal zoom controls (50–300%) while browser page zoom stays disabled.
• Accounts (optional, hidden for now) — sign in with a 3ho.org site account (username or email); cross-device favorites sync (non-destructive merge, tombstoned deletions, last-write-wins on the server). Login unlocks sync, never core content. Since 2026-09-04 the sign-in entry points are hidden (ACCOUNT_SIGN_IN_ENABLED = false in src/lib/features.ts) because attendees cannot create accounts yet; see docs/ACCOUNTS.md.
• Home before the event — / lists every event 3HO publishes (featured + rows, one tap downloads and opens), the latest announcements and news & posts; each event has its own home at /event (hero + sections). Synced events render in the full app experience (Program/Favorites/Teachers/Info/Map/Menus). Sync Lab (/sync-lab, internal) remains the backend test bench. See docs/HOME.md.
• Contact form — saves to a local outbox first, then sends to the WordPress endpoint when online.
• Landings — designed promo pages rendered from data (src/data/landings.json; A Woman's Renewal Experience is the first, see docs/LANDINGS.md), install tutorial, and an account entry in the global header.

Documentation

Start at the docs index for the full map of docs. Key entries:

• PRODUCT.md — who it's for, purpose, brand, principles.
• DESIGN.md — the visual system.
• docs/PROJECT-MEMORY.md — living context & decision log.
• docs/ROADMAP.md — phased plan (backend → native → community → multi-event → commerce).
• docs/BACKEND.md · docs/ACCOUNTS.md · docs/NATIVE.md · docs/MESSAGING.md · docs/TEACHERS.md · docs/LOCAL-NETWORK.md · docs/FEATURES.md — architecture & feature plans.
• CHANGELOG.md — notable changes (Keep a Changelog format).
• CLAUDE.md — contributor/agent guidance and the git workflow.

Stack

• Next.js 15 App Router, static export (output: "export")
• React 19 + TypeScript
• Tailwind CSS v4, shadcn/ui-style lightweight components
• Dexie / IndexedDB for local favorites, agenda, event store, and contact outbox
• @ducanh2912/next-pwa (Workbox) for the service worker
• Capacitor 8 — ios/ and android/ native projects are committed and synced
• Backend: custom REST on WordPress + MySQL (versioned bundle, opaque bearer tokens)

Getting started

npm install
npm run dev

Open http://localhost:3000 (or npm run dev -- -p 3011 for an alternate port).

Scripts

Script	What it does
npm run dev	Local dev server
npm run typecheck	TypeScript check (tsc --noEmit)
npm run lint	ESLint
npm run build	Production build → static export in out/
npm run cap:sync	Build + sync the static export into the native projects
npm run pull-program	Import the published Teacher & Musician program from the checkout feed

Validation before merging

npm run typecheck && npm run lint && npm run build

Routes export as flat files (out/map.html, out/info.html, …) — verify rendered content in out/, not only in source. Full checklist in CLAUDE.md.

PWA / offline behavior

• Manifest is generated by src/app/manifest.ts; icons live in public/icons/.
• The service worker is generated at build time by @ducanh2912/next-pwa.
• An offline preloader (src/components/offline-preloader.tsx) pre-caches every route and static asset under a versioned cache (currently solstice-full-offline-v57).
• Cache rule: any visible UI/content/asset change requires bumping the cache version in both src/components/offline-preloader.tsx and next.config.ts, kept in sync.
• First load requires internet; afterwards the whole app works offline.
• All personal state (favorites, agenda, outbox, synced events) is local-first in IndexedDB; favorites additionally sync to the backend when signed in.

Installability: Android Chrome → menu → Install app; iPhone Safari → Share → Add to Home Screen (in-app tutorial at /install).

Native apps (Capacitor)

ios/ and android/ are committed (app id org.threeho.summersolstice2026). Workflow:

npm run cap:sync
npx cap open ios
npx cap open android

Native-only features: agenda reminders 15 minutes before favorited sessions (@capacitor/local-notifications) and push-registration groundwork (@capacitor/push-notifications — device token registered with the backend after sign-in; server-side sending ships with the messaging phase). Both are no-ops in the browser/PWA. Details in docs/NATIVE.md.

Content pipeline

Two sources feed the static data in src/data/:

1. Booklet extraction (initial) — program.json, venues.json, categories.json, info-pages.json, teachers.json were extracted from 01_SSOL_booklet_2026.pdf. Extraction is imperfect; see TODO_CONTENT_REVIEW.md before publishing widely.
2. Checkout feed import — npm run pull-program (scripts/pull-program.mjs) merges the published Teacher & Musician program from the registration platform (register.3ho.org presenter bundle) into the JSON files: presenter-* entries are replaced wholesale with stable ids (favorites survive reschedules), teachers are enriched by name match, and photos are downloaded to public/images/teachers/. Supports --base, --event, --dry-run, --insecure. See docs/TEACHERS.md.

Backend & accounts

The app consumes a versioned REST bundle from the 3ho-solstice-app WordPress plugin (implemented in the 3ho.org repository): auth (opaque bearer tokens on WordPress users), sync (event bundles with since/ETag), and devices (push tokens). The backend origin is configurable via a shared base-URL override; the app remains fully usable logged out and offline. See docs/BACKEND.md and docs/ACCOUNTS.md.

Contact form sending

The app is a static export, so it cannot send email by itself. The contact form saves messages locally first, then posts them to NEXT_PUBLIC_CONTACT_ENDPOINT when online. Production setup uses wordpress/3ho-solstice-contact-endpoint.php on the 3HO WordPress site, which exposes:

https://www.3ho.org/wp-json/3ho-solstice/v1/contact

Public app variables (embedded at build time — update Vercel env vars before deploying):

NEXT_PUBLIC_CONTACT_ENDPOINT="https://www.3ho.org/wp-json/3ho-solstice/v1/contact"
NEXT_PUBLIC_CONTACT_EMAIL="[email protected]"   # fallback email-draft target only

The automatic recipient is configured on WordPress (define('THREEHO_SOLSTICE_CONTACT_TO_EMAIL', '…') — [email protected] in production). Without the endpoint, messages stay saved locally and can be opened as email drafts.

Contributing workflow

Every change set goes on its own type/topic branch, then push and merge on completion; update CHANGELOG.md and any relevant docs with each change, and bump the offline cache when the change is user-visible. Full rules are in CLAUDE.md (git workflow, changelog, and documentation discipline).