Skip to content
iamyajatPublic

About

A quiet home for the names, hymns, and prayers of the Hindu tradition — offered here for reading, recitation, and remembrance.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Paramatma

A quiet, readable home for Hindu scriptures — 108 names (ashtottara), aartis, bhajans, stotras, and sahasranamas — in Devanagari with pronunciation and meaning. Built with Next.js and MongoDB.

Setup

  1. Copy .env.example to .env.local and fill in:

    • MONGODB_URI — a MongoDB Atlas connection string (include the database name)
    • ADMIN_PASSWORD — the password for /admin
    • SESSION_SECRET — a random 32+ character string (openssl rand -base64 32)
    • NEXT_PUBLIC_SITE_URL — http://localhost:3000 for local dev
    • NEXT_PUBLIC_GA_ID — Google Analytics 4 measurement ID (optional, see Analytics)
  2. Install dependencies and seed a few sample works:

    npm install
    npm run seed
  3. Run the dev server:

    npm run dev

    Visit http://localhost:3000, and http://localhost:3000/admin to manage content.

Adding real content

Content is entered through /admin — create a deity, then a work under it, pasting the text into the bulk-entry format shown in each editor (instructions appear above the content field for each content type). Saving parses the text into individual verse/name documents and publishes immediately when status is set to "Published".

Notes

  • Data model: each verse/name is its own MongoDB document (not nested in an array), so it can later be individually vector-embedded for semantic search — see atlas/README.md.
  • OG images: auto-generated per work at /[type]/[slug]/opengraph-image. They render English text only — the underlying renderer (satori) doesn't shape Devanagari conjuncts correctly, so scripture text itself is kept off the share image. The actual site pages are unaffected, since real browsers shape Devanagari correctly.
  • Fonts: src/assets/fonts/ holds static (non-variable) TTF files used only for satori-rendered images (OG images, favicons), under the SIL Open Font License — Eczar for OG images, plus a Tiro Devanagari Sanskrit TTF (extracted from the same cached file next/font/google already serves the real site, so the ॐ mark matches pixel-for-pixel) for the app icon.
  • PWA: the site is installable (manifest + icons + service worker) and keeps previously visited pages readable offline. src/lib/brand-icon.tsx is the one design used everywhere — ivory background, gold ॐ, matching om-mark.tsx exactly — rendered live via next/og for src/app/icon.tsx and apple-icon.tsx; npm run generate-icons renders the sizes Next can't generate itself (favicon.ico, and the PWA manifest's public/icons/*.png) and writes them to disk. Re-run that script after changing the design. public/sw.js is a small hand-written service worker (network-first for pages, cache-first for static assets, /admin always bypassed) — no build plugin, so it isn't tied to webpack vs. Turbopack. It only registers in a production build (ServiceWorkerRegistration checks NODE_ENV) and actively unregisters itself under next dev — dev-mode bundle URLs aren't content-hashed, so a cache-first SW left over from a previous next start will otherwise keep serving stale JS chunks through later next dev runs.

Analytics

Google Analytics 4 is wired in through @next/third-parties. Nothing loads and nothing is sent unless NEXT_PUBLIC_GA_ID (a G-XXXXXXX measurement ID) is set, so local dev and preview deploys never touch the property. Traffic under /admin is excluded in code.

Everything goes through track() in src/lib/analytics.ts, which strips empty params and truncates values to the 100 characters GA4 accepts. <SiteAnalytics /> in the root layout mounts the gtag script plus three collectors:

  • RouteAnalytics — pageviews on client-side navigation and scroll_depth milestones (25/50/75/90%), with a content_group for the section.
  • InteractionAnalytics — app_open (installed vs browser tab, theme), outbound_click, contact_click, print, and the PWA install funnel. It also turns any data-analytics-annotated link into a select_item event, which is how the server-rendered cards and nav report clicks.
  • WebVitalsAnalytics — LCP/CLS/INP/FCP/TTFB as web_vitals events.

Component-level events cover the product surfaces:

Area Events
Reading work_view, work_read_time, reader_text_size, reader_pronunciation_toggle, reader_meanings_toggle, reader_menu_open, reader_menu_action, verse_copy
Audio audio_play, audio_pause, audio_resume, audio_skip, audio_seek, audio_verse_complete, audio_work_complete, audio_error
Search search_open, search, search_no_results, search_submit, search_result_click, search_recent_click, search_browse_deities
Saves work_save, work_unsave, saves_tab, saves_filter
Collections collection_create, collection_delete, collection_item_add, collection_item_remove, collection_share, collection_import
Sharing & chrome share, share_cancelled, theme_change, select_item, bottom_nav_more_open

Custom parameters (work_type, deity_slug, result_type, search_term, …) need to be registered as custom dimensions in the GA4 property before they show up in reports.

One setting to change in GA4: under Data streams → the web stream → Enhanced measurement, turn off "Page changes based on browser history events". The app sends its own pageview for each client-side navigation, so leaving that on double-counts them.

About

A quiet home for the names, hymns, and prayers of the Hindu tradition — offered here for reading, recitation, and remembrance.

Resources

Stars

1 star

Watchers

0 watching

Forks

Contributors

Languages