AskMukthiGuru — AI Spiritual Guide & Knowledge Platform

Active release baseline — verified 2026-08-12. The supported frontend gate is npm run build; source lint is expected to have zero errors; npm audit --omit=dev must be clean. See the release evidence pack for the complete safety, documentation, and privileged-integration checklist. Historical counts elsewhere in this document are architectural context, not live service assertions.

An AI-powered spiritual guide rooted in the teachings of Sri Preethaji & Sri Krishnaji. Built with a 12-layer RAG pipeline, dual-level LightRAG knowledge graph, second-brain memory vault, real-time guardrails, and cross-platform native mobile & web UI.

Developer Navigation:

• Architecture & Developer Guide: docs/DEVELOPER_GUIDE.md & docs/COMPLETE_BACKEND_ARCHITECTURE.md
• Prioritized Backlog & System Status: docs/PRODUCT_OPPORTUNITIES.md (roadmap merged in as the "Roadmap — Execution Strategy" section)
• Operational Runbooks: docs/runbooks/ (BENCHMARK_RUNBOOK.md, CREDENTIALS_GUIDE.md, STREAM_PROTOCOL.md)
• Lessons Learned & Invariants: lessons.md & AGENTS.md

---

Technical Stack & Architecture

---

Core Platform Capabilities

1. LightRAG & Knowledge Base Ingestion

• Qdrant Vector Base (spiritual_wisdom): Ingested 89,053 items covering books, 450+ YouTube discourses, meditations, and lectures.
• Neo4j Knowledge Graph: 7,601 nodes (7,498 base concept nodes + 103 OKF 5-node transformation arc nodes).
• High-Throughput Auto-Scaling Ingestion: scripts/ingest_lightrag_data.py directly scrolls Qdrant payloads with asyncio worker pools, fast LLM timeouts, and atomic .tmp -> .json checkpointing (data/lightrag_checkpoint.json).
• Contextual Re-ingest Engine: Reconstructs full documents, re-chunks with contextual grounding, and populates spiritual_wisdom_contextual.

2. Second Brain Vault & Personalization Memory

• Second Brain Vault (second_brain_vault): Multi-tenant collection in Qdrant indexed with user_id keyword filters. User notes live encrypted in Postgres (user_brain_nodes), vectors in Qdrant.
• User Familiarity Classification: classify_user_familiarity dynamically adapts response tone across 3 tiers:
  • Seeker: Clear, accessible explanations of Sanskrit and spiritual terms.
  • Practitioner: Balanced guidance focusing on meditation techniques and internal state shift.
  • Advanced Meditator: Deep philosophical terms and neurobiological insights.
• 3-Tier Memory Retention & Automated Cleanup:
  • Tier 1 (Ephemeral): Redis 15-minute sliding TTL (EPHEMERAL_TTL = 900).
  • Tier 2 (Transient): 90-day retention for chat logs and query telemetry.
  • Tier 3 (User Core Vault): Protected user core memory. Inactive accounts (>365 days) automatically purged via scripts/ops/cleanup_inactive_user_data.py.
• GDPR Privacy Controls: Full user control via DELETE /api/memory/reflections and POST /api/memory/forget.

3. 12-Layer RAG Pipeline

1. Zero-Shot Input Rail: Safety and intent guardrails via Instructor.
2. Semantic Pre-Router: Zero-LLM embedding-based query routing.
3. Intent Classification: Identifies casual, distress, meditation, or philosophical queries.
4. Query Decomposition: Multi-hop query splitting for complex questions.
5. Parent-Child & Knowledge Tree Navigation: Contextual hierarchy retrieval.
6. Hybrid Search: Qdrant dense vector search + LightRAG Neo4j graph traversal.
7. Cross-Encoder Reranking: bge-reranker-v2-m3 (GPU/MPS) or mmarco-mMiniLMv2-L12-H384-v1 (CPU).
8. CRAG Document Grading: Filters irrelevant retrieved contexts.
9. Guru Tone Adapter: Adapts responses to Sri Preethaji / Sri Krishnaji voice personas.
10. Context-Aware Generation: Bounded conversation memory injection.
11. Chain of Verification (CoVe): Verification of factual claims.
12. Self-RAG Faithfulness & Output Rail: Final quality gate and safety filter.

4. Interactive Obsidian-Style Knowledge Graph

• Accessible on /knowledge-graph for all visitors.
• Features force-directed 2D/3D graph visualization with glow effects, node dragging, zoom, and live search.
• Includes automatic fallback to cached demo data if graph backend is cold.

5. Native Mobile Experience (Capacitor 8)

• Single codebase targeting Web, iOS, and Android (com.askmukthiguru.app).
• Uses HashRouter inside Capacitor WebView (https://localhost/) for seamless client-side routing.
• Integrated Push Notifications (@capacitor/push-notifications -> FCM & APNs).
• Google & Apple OAuth native deep link handling (com.askmukthiguru.app://auth-callback).

---

Quickstart & Local Development

1. Makefile Commands (Recommended)

2. Running Full Docker Stack

Ensure Docker Desktop is running on macOS, then execute:

# Set Docker binary PATH and run docker compose via safe script (bypasses keychain issues)
cd backend && bash ../scripts/docker-safe.sh docker compose up -d --build

Access local endpoints:

• Main Web Application: http://localhost
• Admin Dashboard: http://localhost/admin
• Knowledge Graph UI: http://localhost/knowledge-graph
• FastAPI Backend Health: http://localhost:8000/api/health
• Neo4j Browser: http://localhost:7474
• Jaeger Tracing: http://localhost:16686

3. Local Development Without Docker Containers

To run services locally on host machine:

# 1. Start core infrastructure containers only (Qdrant, Neo4j, Redis)
cd backend && bash ../scripts/docker-safe.sh docker compose up -d qdrant neo4j redis

# 2. Run backend FastAPI server (in terminal 1)
cd backend
.venv/bin/uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 3. Run frontend Vite server (in terminal 2)
npm install
npm run dev

Note: backend/app/config.py automatically normalizes container hostnames (http://qdrant:6333 -> http://localhost:6333) when executing directly on host Python outside Docker.

---

Data Ingestion & Maintenance Runbook

Running LightRAG Batch Ingestion

To resume or execute full LightRAG knowledge graph ingestion directly from Qdrant:

CONCURRENCY_WORKERS=8 backend/.venv/bin/python scripts/ingest_lightrag_data.py

• Progress is stored atomically in data/lightrag_checkpoint.json.
• Logs stream to stdout and append to data/lightrag_ingestion.log.

Automated Inactive User Memory Cleanup

To purge inactive user data (>365 days inactive):

backend/.venv/bin/python backend/scripts/ops/cleanup_inactive_user_data.py --days 365

---

Directory & Repository Structure

askmukthiguru/
├── backend/                       # FastAPI Python application
│   ├── app/                       # Routes, config, dependencies, middleware
│   ├── rag/                       # 12-layer RAG nodes, prompts, graph strategies
│   ├── services/                  # Qdrant, Neo4j, LightRAG, Second Brain services
│   ├── scripts/ops/               # Automated maintenance & TTL cleanup scripts
│   └── tests/                     # Pytest suite (edge cases, quality gate, nodes)
├── src/                           # React 18 Frontend Application
│   ├── components/                # UI components (Chat, KG visualizer, Admin)
│   ├── pages/                     # App page views
│   └── lib/                       # API clients, backend URL resolvers
├── docs/                          # Comprehensive Documentation
│   ├── runbooks/                  # Operational runbooks (Benchmark, Credentials, AB Test)
│   ├── archive/                   # Historical audit reports & completed plans
│   ├── COMPLETE_BACKEND_ARCHITECTURE.md
│   ├── DEVELOPER_GUIDE.md
│   └── PRODUCT_OPPORTUNITIES.md   # UX/hardcoding audit + merged roadmap
├── scripts/                       # High-level data ingestion & eval scripts
│   └── ingest_lightrag_data.py   # High-throughput LightRAG Qdrant scroll script
├── handoff.md                     # Latest session status & operational handoff
├── lessons.md                     # Lessons learned & architectural invariants
└── Makefile                       # Developer command orchestrator

---

Environment Variables Configuration

Populate key environment variables in backend/.env:

---

Ephemeral chat attachments

The chat composer accepts text and office documents (.txt, Markdown, CSV/TSV, JSON, XML, HTML, YAML, DOCX, PPTX, XLSX), PDFs, images, audio, and video. Each selected file is sent to POST /api/chat/upload, where the backend applies a 10 MB per-file cap and 50 MB combined cap, extracts bounded evidence using PDF/OOXML text extraction, OCR, or local Whisper transcription, and returns an attachment_context value for the next chat turn. Upload bytes are not persisted or indexed automatically. The subsequent /api/chat or /api/chat/stream request carries that context separately from user_message; the RAG generation prompt marks it as untrusted evidence and shared caches/coalescing are bypassed or scoped by an attachment digest.

The upload path is intentionally an extraction MVP, not a corpus-ingestion shortcut. Durable indexing, page/frame citations, malware scanning, resumable uploads, and asynchronous job status remain separate production hardening work and require explicit design before enabling persistence.

License & Author

Developed by Harshodai Kolluru. Built with AI pair-programming assistance (Anthropic Claude, Google Gemini, GitHub Copilot, and Lovable). All rights reserved.

Security & Release Readiness (Jul 31, 2026)

AAL2 / MFA Step-Up

• Frontend: useRequireAuth / useAdminGuard call supabase.auth.mfa.getAuthenticatorAssuranceLevel() on every session load and redirect to /auth/mfa when aal2 is required. MFAChallengePage falls back to verified TOTP factors from the session.
• Backend: require_aal2 dependency (backend/services/auth_service.py) + probe route GET /api/health/mfa (tested by backend/tests/test_aal2_dependency.py, 12 tests). Test auth backdoor honors X-Test-Aal header.

Row-Level Security

• Migration supabase/migrations/20260728103548_85070891-f7bf-4835-94db-4246463b3813.sql (UPDATE WITH CHECK) + idempotent 20260730000000_verify_rls_with_check.sql.
• Cross-user verification: backend/scripts/verify_rls_policies.py (ephemeral Alice/Bob via Admin API, 12 probes) — runs nightly against prod via .github/workflows/nightly-rls.yml (set repo secrets SUPABASE_URL/SUPABASE_SERVICE_ROLE_KEY first).
• E2E: tests/e2e/rls-cross-user.spec.ts (UI deep-link isolation + REST probe).
• Supabase dashboard (Pro): Auth → Providers → Email → Prevent the use of leaked passwords (HIBP); verify with backend/scripts/verify_leaked_password_protection.py.

Metrics Parity (UI ↔ Backend)

• Shared contract: backend/app/schemas/metrics.py (pydantic) ↔ src/lib/metricsSchema.ts (zod), parity tested by src/test/metricsSchema.test.ts.
• GET /api/metrics (auth, RLS-scoped client, anonymous → zeroed payload) consumed by src/hooks/useMetrics.ts (60s TTL cache, refetch on conversation:updated).

Proactive Healing Courses (Streak-Based)

• backend/services/healing_course_service.py: assigns a healing course only on distress streaks — ≥2 consecutive turns, ≥3-of-5 frequency, escalating severity, or same SufferingSignal ≥2× in 24h; never duplicates an active course (user_course_progress).
• API: POST /api/healing-course/assign, POST /api/healing-course/progress.
• UI: src/components/chat/HealingPathCard.tsx shows the card with dismissal and assignment.

Langhanam Unified Guru Voice (Default-Off)

• langhanam_voice_enabled=false by default; GURU_VOICE_MODE=prompt|adapter selects variant; benchmark backend/benchmarks/guru_voice_benchmark.py gates flipping the flag at ≥4.0/5.0 (needs a live LLM run). Reference voice: backend/services/guru_voice_langhanam.py (Langhanam transcript excerpt).