Epic - Divine Guidance Application

A React-based frontend application that provides spiritual guidance from sacred texts across multiple religions and languages.

Features

• Multi-Religious Support: Bhagavad Gita, Vedas, Quran, Bible, Guru Granth Sahib, Tripitaka, Tao Te Ching, Analects of Confucius, Dhammapada, Upanishads, Talmud, and Avesta
• Multi-Language Support: English, Hindi, Spanish, Portuguese, French, German, Arabic, Punjabi, Urdu, and more
• Four Guidance Modes: Seek Guidance, Understand, Reflect, and Ask Me (Socratic) — see below
• Crisis-Aware Compassion: Detects acute distress and responds with human warmth and real-world help, never a verse-dump
• Intellectual Humility: Every substantive response is accompanied by a transparency disclaimer
• Interactive UI: Breathing background animations, floating particles, and spiritual loader
• Responsive Design: Works seamlessly on desktop, tablet, and mobile devices
• Performance Optimized: Lazy loading, code splitting, and efficient rendering

Guidance Philosophy

Epic is built around a few deliberate principles:

• Lead with the human, not the verse. When a message signals acute distress or crisis, the app responds first with compassion and concrete real-world resources (helplines, support links) instead of parsing scripture into quotes.
• Meet people where they are. Four distinct modes let a user choose between comfort, learning, contemplation, and self-inquiry.
• Stay humble. Substantive responses carry a transparency disclaimer making clear this is reflective guidance, not authoritative religious ruling.

Guidance Modes

Mode	Button	What it does
Guidance	Seek Guidance	Warm, personalized reflections rooted in scripture for your situation
Understand	Understand	Educational answers about religious teachings, concepts, and history
Reflect	Reflect	A single passage to sit with quietly, plus an open question to carry
Socratic	Ask Me	Returns the questions a tradition might gently ask you, instead of answers

Technology Stack

Core Technologies

1. React 19 - Modern React with hooks and functional components
2. Vite - Fast build tool and development server
3. FontAwesome - Icon library

Design System

Colour is derived, not hand-picked. Each of the ten traditions contributes a single hue and saturation to src/styles/tokens.css, and every surface, ink and accent shade is generated from it at fixed lightness steps. That keeps the themes consistent and makes WCAG AA contrast a property of the system rather than something to remember — tokens.contrast.test.js checks all ten traditions against both colour schemes on every run. Dark mode follows the operating system.

Performance Features

1. Code Splitting - Lazy loading of components and chunks
2. Service Worker - Caching and offline functionality
3. Canvas Optimizations - Hardware-accelerated animations
4. Memoization - React.memo and useMemo for performance
5. Bundle Optimization - Tree shaking and minification

Installation

# Clone the repository
git clone <repository-url>
cd epic

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

Project Structure

src/
├── components/          # React components
│   ├── BreathingBackground.jsx
│   ├── FloatingParticles.jsx
│   ├── GuidanceForm.jsx
│   ├── ResponseSection.jsx
│   └── ...
├── hooks/              # Custom React hooks
│   ├── useGuidance.js
│   └── useTheme.js
├── pages/              # Routed pages
│   └── ConversationsPage.jsx
├── styles/             # CSS stylesheets
├── test/               # Test setup (jsdom + jest-dom)
├── scriptures.js       # Single source of truth for all 13 sacred sources
├── prompts.js          # Prompt templates, fed by the scripture registry
├── responseParser.js   # Parses the labelled response contract
├── crisisDetection.js  # Crisis-language detection + compassionate message
├── utils.js            # Utility functions
└── App.jsx             # Main application component

The scripture registry

Everything that varies per sacred text — its label, glyph, theme, blurb, placeholder copy, example verses, citation format, reference URL pattern and breadth hint — lives in one row in src/scriptures.js. The header, the form, the theme, the response heading, the archive filters and every prompt read from it. Adding a tradition is one row, not ten edits across the codebase.

Privacy

Nothing you write is stored unless you explicitly ask for it to be. The "share this anonymously" checkbox under the form is off by default, and only when it is ticked does a reflection reach the public archive. What people bring here reveals religious belief and personal circumstance — special-category data under GDPR Article 9 — which warrants explicit opt-in rather than silent collection.

Input that trips crisis detection is never sent to the model and never stored.

Performance Optimizations

Bundle Size

• Code Splitting: Separate chunks for React, prompts, and app logic
• Lazy Loading: ResponseSection component loaded on demand
• Tree Shaking: Unused code eliminated during build
• Minification: Aggressive code and CSS minification

Runtime Performance

• Memoization: Components and expensive calculations cached
• Canvas Optimization: Hardware acceleration for animations
• Caching: Service worker for static assets and API responses

Memory Management

• Component Cleanup: Proper cleanup of event listeners and animations
• Request Cancellation: In-flight guidance requests aborted when superseded

Development

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run preview - Preview production build
• npm run clean - Clean build directory
• npm test - Run the test suite once
• npm run test:watch - Run tests in watch mode
• npm run coverage - Run tests with a coverage report

Testing

The project uses Vitest with @testing-library/react and a jsdom environment.

npm test

Coverage includes:

• Crisis detection — language matching and the compassionate response shape
• resolveMode — prompt/system selection across all four modes
• GuidanceForm — the four-mode toggle (render, active state, callbacks)
• ResponseSection — crisis support card, humility disclaimer, and normal scripture parsing

Tests run automatically in CI (.github/workflows/ci.yml) on every push and pull request, and gate the GitHub Pages deploy (.github/workflows/deploy.yml).

Performance Monitoring

The application includes built-in performance monitoring:

• Parse time tracking
• Render time optimization
• API call performance
• Memory usage monitoring

Deployment

The application is optimized for deployment on Vercel, Netlify, or any static hosting service. The build process creates optimized static files in the dist/ directory.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT License - see LICENSE file for details.