# DivineConnect (The Braj Dham Seva Trust) — Master Implementation Roadmap

**Project:** DivineConnect (The Braj Dham Seva Trust — TheBraj.org)  
**Tagline:** Discover • Connect • Explore • Serve  
**Document Type:** Single Authoritative Master Blueprint (`DIVINECONNECT_MASTER_ROADMAP.md`)  
**Status:** Unified Working Development Blueprint (Single Source of Truth)  
**Greeting:** Radhe Radhe! 🙏  
**Technology Baseline:** **Laravel 13 + PHP 8.4 + Blade Templates + Tailwind CSS v4 + MySQL** (Officially Locked & Confirmed)

---

## 1. Executive Summary & Architecture Foundation

DivineConnect is a **Global Spiritual & Religious Digital Ecosystem** designed to seamlessly connect sacred places, pilgrimage journeys, festivals, seva/donations, local businesses, and devotee communities onto one unified platform.

### Confirmed Technology Baseline (No Next.js / Node.js Rewrite)
The technology stack is officially confirmed as a **Modular Monolith**:
- **Backend Framework:** Laravel 13 (PHP 8.4)
- **Frontend / Rendering:** Laravel Blade Templates + Tailwind CSS v4 + Alpine.js
- **Database:** MySQL (`dham_seva_db`) via Eloquent ORM & Artisan Migrations
- **Styling & Design Tokens:** Tailwind CSS v4 (`resources/css/tokens.css` + `frontend.css`)
- **Caching & Queues:** Redis / Database Queue
- **Hosting / Storage:** Local / Cloud Server + S3 / Cloudflare R2 Object Storage for Media

```
┌────────────────────────────────────────────────────────────────────────┐
│                              DIVINECONNECT                             │
│                  Unified Spiritual & Seva Ecosystem                    │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
           ┌────────────────────────┴────────────────────────┐
           ▼                                                 ▼
┌──────────────────────────────┐              ┌──────────────────────────────┐
│       Public Frontend        │              │     Admin Console (RBAC)     │
│   (Blade + Tailwind CSS v4)  │              │   (Blade + Page Builder)     │
└──────────────┬───────────────┘              └──────────────┬───────────────┘
               │                                             │
               └──────────────────────┬──────────────────────┘
                                      ▼
                        ┌───────────────────────────┐
                        │    Laravel 13 Controllers  │
                        │   & Service Action Layer  │
                        └─────────────┬─────────────┘
                                      ▼
                        ┌───────────────────────────┐
                        │      MySQL Database       │
                        │ (Relational Core Schema)  │
                        └───────────────────────────┘
```

---

## 2. Core Guardrails & Non-Negotiable Decisions

1. **NO E-Commerce Cart or Checkout:** The Spiritual Marketplace is **100% enquiry-based** (IndiaMART / Justdial model). Devotees click **"Chat on WhatsApp"** to connect directly with the vendor. There is strictly no online cart, product checkout, delivery tracking, or order fulfillment.
2. **Dedicated Seva & Donation Gateway:** Online payment processing is reserved exclusively for Seva and Donations using **Razorpay**.
3. **FCRA & Indian Citizen Lock:** In compliance with Indian FCRA laws, donations are strictly in **INR (`₹`)** with mandatory Indian Citizenship declaration. Foreign cards and foreign currencies are blocked until FCRA certification is secured.
4. **Strict Financial Separation (Rule 12):** Trust donations, third-party verified campaigns, vendor subscriptions, and creator support are maintained in **completely separate, non-commingled accounting ledgers**.
5. **Commercial GST Billing:** All vendor subscriptions and featured business listings are billed through a separate commercial technology entity issuing **18% GST compliant tax invoices** (never deposited into Trust 80G accounts).
6. **Open Public Browsing:** Pilgrims and visitors can browse sacred places, yatras, festivals, and business listings freely without mandatory login. Login is required only for submissions, reviews, and personalized dashboard actions.
7. **No Code / Layout Disruption:** Existing working layouts, blade views, and routes remain intact. New capabilities are added additively and progressively.

---

## 3. Official Color Commission & Design System

The visual design system adheres strictly to the **"Sattvic, Serene & Premium Divine"** philosophy:

| Color Role | Token Name | HEX Code | UI Placement & Spiritual Significance |
|:---|:---|:---|:---|
| **Primary Brand** | `divine-gold` | `#D97706` | Brand emblem, primary CTA buttons, search focus glow, aarti jyot. |
| **Gold Dark** | `divine-gold-dark` | `#B45309` | Hover states, active links, accents. |
| **Gold Light** | `divine-gold-light` | `#FEF3C7` | Highlight badges, tag pills, selected states. |
| **Secondary Anchor** | `divine-navy` | `#132338` | Mayur Neel (deep peacock navy) for sticky header, major headings, admin sidebar. |
| **Canvas Background** | `divine-sand` | `#FBF9F5` | Mathura-Vrindavan sandstone ivory canvas; gentle on eyes, prevents fatigue. |
| **Card Surface** | `divine-card` | `#FFFFFF` | Card backgrounds, directory cards, form panels. |
| **Seva & Nature** | `divine-seva` | `#1B7943` | Tulsi green for verified shields, seva badges, donation progress bars. |
| **WhatsApp Action** | `divine-whatsapp` | `#25D366` | Official WhatsApp green for marketplace enquiry buttons. |
| **High Alert / Utsav**| `divine-kumkum` | `#B91C1C` | Temple vermillion/kumkum for live aarti badges, emergency contacts. |

---

## 4. Authentication & Security Architecture

### 4.1 Progressive Lockout Engine & Visual Countdown
To protect against brute-force attacks while preserving user convenience:
- **Attempts 1 & 2:** Generic error message: *"The login details are incorrect. Please check your credentials and try again."* (Never reveals whether the email exists).
- **Attempt 3 (Failed):** Triggers a **60-Second Temporary Lockout**.
  - Visible live countdown timer (`00:59` to `00:00`) on `/auth/login`.
  - Backend strictly enforces lockout via `lock_until_timestamp`.
- **Final Attempt (Attempt 4):** When the timer expires, the user gets **exactly 1 final chance**.
  - If correct $\rightarrow$ Logged in, failure counter reset.
  - If failed $\rightarrow$ Password login permanently locked for that session; **Mandatory Dual-OTP Password Recovery** is enforced.

### 4.2 Mandatory Dual-OTP Password Reset
When progressive lockout is triggered or a password reset is requested:
- The user must provide their registered account identifier.
- The system dispatches **TWO independent OTPs simultaneously**:
  1. **Email OTP:** Sent to the registered email address.
  2. **Mobile / WhatsApp OTP:** Sent via SMS or WhatsApp to the registered mobile number.
- **Enforcement:** New password creation is permitted **only when BOTH OTPs are successfully validated**.
- **Session Revocation:** A successful password reset immediately terminates all active sessions, un-trusts registered devices, and clears existing PINs.

### 4.3 Trusted Devices & 4-Digit Quick PIN
- On new devices, Quick PIN is **never shown** initially.
- Upon successful password login on a new browser/device, user is prompted:  
  `"Would you like to trust this device?" [Yes, Trust Device] [No, Skip]`
- If user selects "Yes", they configure a **4-digit Quick PIN** (weak patterns like `0000`, `1234`, `1111` are rejected).
- On subsequent visits on that specific device, user can log in with their **4-digit PIN** without entering their full password.
- **Admin Privilege Rule:** Super Admin and Staff roles **must use Password + 2FA**. Quick PIN alone is strictly forbidden for administrative access.

---

## 5. 5-Level Global Location Architecture & Admin Location Manager

### 5.1 Worldwide Geographic Hierarchy
The location engine scales seamlessly from Braj Dham to any sacred destination globally:

`Level 1: Continent → Level 2: Country → Level 3: State/Province → Level 4: District/County → Level 5: City/Locality`

1. **Continents (`continents`):** Asia, Europe, North America, South America, Africa, Oceania.
2. **Countries (`countries`):** ISO-3166-1 alpha-2 codes (`IN`, `US`, `GB`, `NP`, `ID`, `AE`, etc.), dial codes, currency, default timezone, dynamic admin label schema, and `is_active` toggle.
3. **States / Provinces (`states_provinces`):** States, Provinces, Emirates, or Prefectures linked to countries.
4. **Districts / Counties (`districts_counties`):** Administrative districts or counties.
5. **Cities / Localities (`cities_localities`):** Holy cities, towns, and sacred circuits (e.g. *Vrindavan, Mathura, Varanasi, Ayodhya, Kathmandu, Bali, London, New Jersey*) with latitude, longitude, postal codes, and local timezone.

### 5.2 Admin Global Location Manager
Located in Admin Panel under `Settings -> Global Locations`:
- **Toggle Locations ON/OFF:** Super Admin can activate or deactivate any country, state, or city with one click to control geographic rollout.
- **Suggest Missing City Workflow:** If an international town is missing, users can submit **"+ Suggest New City"**, which enters an admin approval queue (`PENDING_REVIEW`).
- **Local Timezone Display:** All sacred places display ritual and darshan timings in their **local timezone** with clear indicator (e.g., `07:00 AM IST` or `06:30 PM EST`).

---

## 6. Multi-Faith Adaptive Architecture

Every sacred place belongs to a `faith_category`:
1. **Sanatan / Hindu** (Mandir, Ashram, Kund, Ghat, Peeth, Math)
2. **Sikhism** (Gurudwara, Takht)
3. **Buddhism** (Monastery / Gompa, Stupa, Vihara)
4. **Jainism** (Derasar, Tirtha)
5. **Christianity** (Church, Cathedral, Basilica, Shrine)
6. **Islam** (Mosque / Masjid, Dargah)
7. **Interfaith & Spiritual Heritage Centers**

**Adaptive UI Engine:** The single place-detail template dynamically maps labels:
- *Sanatan:* Darshan Timings, Aarti & Bhog Schedule, Sampradaya, Presiding Deity.
- *Sikh:* Darbar Sahib Timings, Hukamnama, Langar Details, Jatha.
- *Christian:* Mass & Prayer Schedule, Patron Saint, Denomination.
- *Buddhist:* Monastery Timings, Meditation & Chanting Schedule, School/Tradition.

---

## 7. Seva & Donation Engine — DonateKart Itemized Model

### 7.1 Dual Donation Modes
Super Admin can publish campaigns in two formats:
1. **Flexible Amount Mode:** Donor enters custom amount (₹501, ₹1100, ₹2100, Custom).
2. **Itemized Seva Unit Mode (DonateKart Model):** Specific, transparent physical seva units:
   - *Gau Seva:* Green Fodder Bundle (`₹250 / bundle` — e.g. Target: 400 bundles)
   - *Sadhu Annadan:* Sadhu Bhojan Thali (`₹101 / thali` — e.g. Target: 1,000 thalis)
   - *Winter Seva:* Warm Blanket for Vashnavas (`₹500 / blanket` — e.g. Target: 250 blankets)
   - *Temple Renovation:* Stone/Brick Seva Unit (`₹1,000 / unit`)

### 7.2 UX & Compliance Guardrails
- **Quantity Steppers:** Donors use `- [ 2 ] +` steppers to select seva units.
- **Seva Pledge Summary:** Labeled as **"Seva Pledge Summary"** (strictly NOT an e-commerce cart) leading straight to Razorpay.
- **FCRA Indian Citizen Guardrail:** 
  - Restricted strictly to **INR (`₹`)**.
  - Mandatory checkbox declaration:  
    > *"I confirm that I am an Indian Citizen holding a valid Indian Passport/PAN, and this donation is made from my Indian bank account in full compliance with Indian laws."*
  - Foreign cards are blocked by the gateway.
- **Automated 80G Tax Receipts:** Instant PDF generation with donor PAN, 12A/80G registration numbers, and financial year details upon webhook signature verification.
- **Impact Proofs:** Trust uploads photos/videos of distribution to the **"Impact Updates"** tab, automatically notifying donors.

---

## 8. Spiritual Marketplace & Vendor Subscriptions (Commercial GST Engine)

### 8.1 Pure Enquiry-Based Model (No Cart / Checkout)
- Products and services are displayed with indicative pricing, high-resolution photos, and descriptions.
- Primary CTA is **"Chat on WhatsApp"** (`https://wa.me/...`) with pre-filled enquiry message:  
  *"Radhe Radhe! I saw your listing [Product Name] on DivineConnect. I would like more information."*
- Strictly **no payment collection for products, no shopping cart, no shipping, and no delivery management**.

### 8.2 Three Vendor Subscription Plans
1. **Free Basic Listing (`FREE`):**
   - Displays **"Not Verified"** self-declared badge.
   - Up to 5 product/service listings.
   - Direct WhatsApp enquiry button active.
2. **Verified Business Plan (`VERIFIED_PRO` — Annual):**
   - Mandatory business KYC submission (GST / Udyam / Govt ID).
   - Unlocks **"Verified Vendor"** green shield badge.
   - Up to 50 product/service listings.
   - Priority placement in category search + WhatsApp lead counter dashboard.
3. **Featured / Sponsored Boost (`FEATURED_BOOST` — Monthly / Quarterly):**
   - Category-top spotlight carousel.
   - Distinct, transparent label: **`Sponsored Partner`**.
   - Auto-expires via scheduled task on `end_date`.

### 8.3 Commercial GST Billing Entity Separation
- **Strict Legal Rule:** Vendor subscription revenues **MUST NEVER** touch The Braj Dham Seva Trust's 80G charitable bank account.
- Subscription billing is handled by a separate private commercial technology entity issuing **18% GST tax invoices**.

---

## 9. Volunteer Onboarding & Seva Shift Management

1. **Volunteer Profile Registration:**
   - Devotees apply as volunteers specifying location, travel readiness, and skills:
     * *Medical / First Aid*
     * *Crowd Management & Queue Seva*
     * *Annadan & Kitchen Preparation*
     * *Gau Seva & Animal Care*
     * *Translation & Devotee Guidance*
   - ID proof upload for on-ground verification.
2. **Seva Drive Board:** Trusts and admins post specific upcoming drives (e.g. *"Janmashtami Jal & Parikrama Seva — 50 Volunteers"*).
3. **Shift Booking & Digital QR Seva Pass:**
   - Volunteers book available shifts.
   - Approved volunteers get a **Digital QR Code Seva Pass** in their dashboard for gate check-in.
4. **Seva Hours & Recognition:**
   - Gate coordinators scan QR codes to log check-in/out.
   - Verified hours accrue in the volunteer's profile (`Seva Hours: 32 hrs`), unlocking downloadable **Seva Appreciation Certificates**.

---

## 10. Global Festivals & Utsav Calendar Architecture

1. **Universal Spiritual Festivals:**
   - Complete coverage of major celebrations: Maha Shivratri, Janmashtami, Radhashtami, Govardhan Puja, Holi, Gurpurab, Buddha Purnima, Mahavir Jayanti, Christmas, Eid.
   - Historical background, philosophical significance, fasting/vrat rules, and traditional prasad guidelines.
2. **Today's Panchang / Tithi Card:**
   - Daily spiritual highlight card on homepage and calendar (Tithi, Nakshatra, Moon phase, auspicious observances).
3. **Calendar Integration & Reminders:**
   - One-click **"Add to Calendar (.ics)"** for Google Calendar, Apple Calendar, and Outlook.
   - Automated email/push notification reminders: **3 days prior** and **1 day prior** to major utsavs.

---

## 11. Homepage UX & Screen Layout Blueprints

1. **Top Anchor:** Subtle DivineConnect wordmark and emblem in Mayur Neel and Kesari Gold.
2. **Centerpiece Search Box:** Wide, elegant search bar with rotating spiritual placeholders:
   - *"Search 'Banke Bihari Darshan timings'..."*
   - *"Search '84 Kos Braj Parikrama itinerary'..."*
   - *"Search 'Gau Seva fodder campaigns'..."*
3. **5 Quick-Access Spiritual Pills (Below Search Box):**
   - `[ 🛕 Temples & Sacred Places ]`
   - `[ 🗺️ Yatra Planner ]`
   - `[ 📅 Utsav Calendar ]`
   - `[ 🌿 Gau & Annadan Seva ]`
   - `[ 🛍️ Spiritual Marketplace ]`
4. **Live Trust Micro-Ticker:** Subtle indicator: *"1,200+ Sacred Places • 45+ Verified Trusts • 100% Transparent Seva"*.
5. **Scroll Behavior:** Smoothly transitions into the sticky header containing category navigation and `/auth/login`.

---

## 12. Master Implementation Phases

* **Phase 00 (COMPLETED):** Scope Freeze & Master Roadmap Alignment (Current State).
* **Phase 01: Core Architecture & Data Dictionary Alignment:** 
  - Add database migrations for Continents, Countries, States, Cities, Faith Categories, Campaign Items, and Subscription Plans within the existing Laravel MySQL setup.
* **Phase 02: Progressive Lockout, Dual OTP & Device PIN:**
  - Implement 60s countdown timer on `/auth/login`, Dual OTP (Email + Mobile/WhatsApp), and trusted device PIN storage.
* **Phase 03: 5-Level Global Location Manager:**
  - Build Admin Global Location Manager in existing Admin Console (toggle countries/cities, suggest new city queue).
* **Phase 04: DonateKart Itemized Seva & FCRA Engine:**
  - Itemized quantity steppers, Razorpay donation integration with Indian Citizen/INR lock, and automated 80G PDF receipts.
* **Phase 05: Spiritual Marketplace & Vendor Subscriptions:**
  - Vendor KYC verification, 3 tier plans (`FREE`, `VERIFIED_PRO`, `FEATURED_BOOST`), and 18% GST commercial invoicing.
* **Phase 06: Volunteer Seva Shifts & Digital QR Pass:**
  - Volunteer skills registration, seva drive shift management, QR code check-in pass, and Seva Certificates.
* **Phase 07: Global Festivals, Panchang Card & .ics Calendar:**
  - Multi-faith festival catalog, Today's Panchang card, .ics sync, and 3-day advance reminders.
* **Phase 08: Multi-Faith Detail Templates & Quality Verification:**
  - Adaptive UI labels (Mandir / Gurudwara / Church / Monastery), full regression testing on Laravel PHPUnit suite.

---

*End of DivineConnect Master Implementation Roadmap*  
*Radhe Radhe!* 🙏
