# 🌐 Dham Seva — Crowdfunding & Sacred Public Fundraising Ecosystem
## Master Technical Architecture, Rules & Complete Implementation Roadmap (`pages/crowdfunding.md`)

> **Executive Charter & Core Platform Law:**  
> The **Dham Seva Crowdfunding Platform (धाम सेवा जन-सहयोग व क्राउडफंडिंग महा-अभियान)** is engineered to be India's most transparent, fraud-proof, and sacred humanitarian fundraising ecosystem.  
> **Golden Rule (अटल नियम):** Anyone worldwide can submit a campaign for genuine causes, but **NO CAMPAIGN CAN GO PUBLIC OR ACCEPT A SINGLE RUPEE WITHOUT EXPLICIT ADMIN SCRUTINY & APPROVAL.**

---

## 🧭 System Overview & User Flows

```mermaid
flowchart TD
    subgraph Onboarding["1. दोहरे ऑनबोर्डिंग मार्ग (Dual Ingestion Channels)"]
        A1["मार्ग 1: एडमिन पैनल से सीधे पंजीयन<br><code>/admin/campaigns/create</code>"] --> A2["User ID + Password सेट करें<br>+ प्रूफ डॉक्युमेंट्स अपलोड"]
        A2 --> A3["सीधे Approved & Instant Live"]
        
        B1["मार्ग 2: पब्लिक सेल्फ-रजिस्ट्रेशन<br><code>/fundraiser/register</code>"] --> B2["4-Step विज़ार्ड + मरीज/ट्रस्ट विवरण<br>+ हॉस्पिटल एस्टीमेट / रिपोर्ट्स"]
        B2 --> B3["Status: PENDING_REVIEW<br>🔒 पूर्णतः लॉक व गुप्त"]
    end

    subgraph Verification["2. कड़ा एडमिन गेटकीपर (Verification Gatekeeper)"]
        B3 --> V1["Admin Scrutiny Panel<br><code>/admin/campaigns/{id}/verify</code>"]
        V1 --> V2{"सत्यापन परिणाम"}
        V2 -->|डॉक्टर/अस्पताल पुष्ट| V3["🟢 APPROVE & PUBLISH"]
        V2 -->|अतिरिक्त प्रूफ चाहिए| V4["🟡 REQUEST MORE PROOF"]
        V2 -->|फर्जीवाड़ा / संदिग्ध| V5["🔴 REJECT & BLACKLIST"]
    end

    subgraph Public["3. पब्लिक डोनेशन व वायरल इंजन (Public Engine)"]
        V3 --> P1["पब्लिक पेज: <code>/campaigns/{slug}</code>"]
        A3 --> P1
        P1 --> P2["1-Click गोल्डन सेवा चेकआउट<br>UPI / Razorpay / QR"]
        P1 --> P3["सार्वजनिक दानी सम्मान दीवार<br>(Live Donors Wall + City + Amount)"]
        P1 --> P4["1-Click WhatsApp वायरल शेयर कार्ड<br>(मरीज फोटो + प्रोग्रेस बार)"]
        P1 --> P5["होमपेज क्राउडफंडिंग सेक्शन<br>(Emergency Badge + Live Meter)"]
    end

    subgraph Payout["4. प्रत्यक्ष अस्पताल भुगतान (Direct Hospital Escrow)"]
        P2 --> T1["Dham Seva Escrow Account"]
        T1 --> T2["सीधे अस्पताल / ट्रस्ट के खाते में भुगतान<br>(No Misuse / केस-टू-केस एडमिन प्रबंधन)"]
        T2 --> T3["उपयोगिता प्रमाण पत्र (Discharge Summary)<br>सभी दानियों को ईमेल व WhatsApp"]
    end
```

---

## 🏛️ 1. Two-Way Registration & Account Management

### मार्ग 1: एडमिन द्वारा सीधे नया फंडरेज़र व कैंपेन जोड़ना (`/admin/campaigns/create`)
जैसे **Business Directory** और **Devotee Articles** में एडमिन नया यूजर बना सकता है, वैसे ही क्राउडफंडिंग में 2 मोड्स होंगे:
1. **`🔘 Link Existing User / Fundraiser`**:
   - लाइव सर्च बॉक्स (`#fundraiserSearchInput`) के साथ ड्रॉपडाउन।
   - नाम, ईमेल या मोबाइल नंबर टाइप करते ही तुरंत फ़िल्टर।
2. **`➕ Register New Fundraiser Account`**:
   - पूरा नाम (Full Name) *
   - मोबाइल नंबर (Mobile No) *
   - लॉगिन ईमेल / User ID *
   - लॉगिन पासवर्ड * (डिफ़ॉल्ट ऑटो-सजेस्ट: `Braj@12345` या कस्टम)
   - प्रोफाइल फोटो / अवतार
   - एडमिन क्रेडेंशियल्स तुरंत जनरेट करके फंडरेज़र को दे सकता है ताकि वे अपने डैशबोर्ड (`/fundraiser/dashboard`) में लॉगिन कर सकें।

### मार्ग 2: पब्लिक सेल्फ-रजिस्ट्रेशन (`/fundraiser/register` & `/fundraiser/create`)
- कोई भी पीड़ित, मरीज का परिजन, ट्रस्टी, या समाज सेवक सीधे वेबसाइट पर रजिस्टर कर सकता है:
  - नाम, मोबाइल (OTP सत्यापित), ईमेल और पासवर्ड।
  - 4-स्टेप कैनवस में मरीज/संस्था की समस्या, लक्ष्य राशि (Goal Amount), और दस्तावेज जमा करता है।
  - **स्थिति (Status):** तुरंत **`pending_review`** पर लॉक हो जाती है — जब तक एडमिन अप्रूव न करे, पब्लिक में 1 रुपया भी नहीं लिया जा सकता।

---

## ⚖️ 2. अनिवार्य नियम व सुरक्षा प्रोटोकॉल (Crucial Rules & Guardrails)

*ये नियम धाम सेवा को भारत का सबसे प्रामाणिक व सुरक्षित क्राउडफंडिंग प्लेटफॉर्म बनाते हैं:*

| # | नियम का नाम | विवरण व सुरक्षा प्रभाव |
| :--- | :--- | :--- |
| **Rule 1** | **कड़ा पहचान व संबंध KYC** | मरीज से अभियान कर्ता का संबंध (माता, पिता, पुत्र, स्वयं) सत्यापित होना चाहिए ताकि कोई तीसरा अनजान व्यक्ति किसी के नाम पर पैसे न उगाहे। |
| **Rule 2** | **प्रत्यक्ष अस्पताल एस्क्रो भुगतान** | ₹1,00,000+ के मेडिकल केसों में दान सीधे **अस्पताल के आधिकारिक बैंक खाते** में NEFT/RTGS किया जाएगा। निजी दुरुपयोग शून्य होगा। |
| **Rule 3** | **🚨 2-घंटे फास्ट-ट्रैक समीक्षा** | ICU या आपातकालीन सर्जरी वाले केसों में एडमिन को विशेष **🚨 Emergency** अलर्ट मिलेगा ताकि 2 घंटे में डॉक्टर से पुष्टि कर लाइव किया जा सके। |
| **Rule 4** | **एडमिन फ़ीस पूर्णतः गुप्त (Confidential Admin Discretion)** | **पब्लिक या फ्रंटएंड पर कोई भी फ़ीस शो नहीं होगी।** एडमिन बैकएंड में केस-टू-केस (Case-to-case) परिस्थितियों, हॉस्पिटल नेगोशिएशन और ऑपरेशनल खर्च के अनुसार आंतरिक निर्णय लेगा। |
| **Rule 5** | **विदेशी दान (FCRA / NRI) नियम** | व्यक्तिगत मेडिकल अभियानों में केवल भारतीय बैंक / NRE / NRI दान (पैन कार्ड सहित) लिया जाएगा। केवल FCRA मान्यता प्राप्त ट्रस्ट्स ही विदेशी मुद्रा ले सकते हैं। |
| **Rule 6** | **80G आयकर छूट पारदर्शिता** | केवल पंजीकृत 80G चैरिटेबल ट्रस्ट्स में दान करने पर ही 80G टैक्स छूट मिलेगी। व्यक्तिगत मरीज को दान पर 80G लागू नहीं होता (इनकम टैक्स कानून)। यह रसीद पर स्पष्ट रहेगा। |
| **Rule 7** | **लक्ष्य पूर्ति (Goal Ceiling)** | लक्ष्य राशि (उदा. ₹2,50,000) पूरी होते ही कैंपेन **`Goal Reached`** हो जाएगा और अतिरिक्त दान स्वतः बंद हो जाएगा। डॉक्टर के नए एस्टीमेट पर ही एक्सटेंशन मिलेगा। |
| **Rule 8** | **उपयोग प्रमाण पत्र (Utilization Proof)** | इलाज के 30 दिनों के भीतर डिस्चार्ज समरी व मेडिकल बिल पोर्टल पर अपलोड करना अनिवार्य होगा, जो सभी दानियों को WhatsApp पर भेजा जाएगा। |

---

## 🏷️ 3. श्रेणी-आधारित गतिशील फ़ील्ड्स (Dynamic Category Forms)

*कैटेगरी चुनते ही फॉर्म के इनपुट्स और रिक्वायर्ड डॉक्युमेंट्स स्वतः बदल जाते हैं:*

### 1. 🏥 Medical Treatment & Surgery (चिकित्सा व जीवन रक्षा)
- **फ़ील्ड्स:** मरीज का नाम, उम्र, लिंग, बीमारी (कैंसर, हार्ट, ऑर्गन ट्रांसप्लांट, डायलिसिस, एक्सीडेंट), अस्पताल का नाम, शहर, डॉक्टर का नाम व रजिस्ट्रेशन नंबर, ऑपरेशन तिथि, प्रतिदिन ICU खर्च।
- **अनिवार्य अपलोड्स:** 📄 अस्पताल लेटरहेड पर एस्टीमेट लेटर, 💊 डॉक्टर का पर्चा व टेस्ट रिपोर्ट, 📸 अस्पताल बेड पर मरीज की वास्तविक स्थिति की फोटो, 🆔 मरीज/अभिभावक का आधार कार्ड।

### 2. 🏛️ Trusts, Ashrams & Annakshetra (आश्रम व धार्मिक संस्थाएँ)
- **फ़ील्ड्स:** ट्रस्ट का नाम, रजिस्ट्रेशन नंबर, नीति आयोग दर्पण ID, 80G व 12A नंबर, मुख्य महंत/ट्रस्टी नाम व फोन, सेवा उद्देश्य (संत अन्न क्षेत्र, धर्मशाला, गौशाला), आश्रम का पता।
- **अनिवार्य अपलोड्स:** 📄 ट्रस्ट रजिस्ट्रेशन व पैन कार्ड, 📜 80G व 12A सर्टिफिकेट, 📸 आश्रम व प्रस्तावित निर्माण ब्लूप्रिंट, 🏦 बैंक कैंसिल्ड चेक।

### 3. 🐄 Gau Seva & Animal Care (गौ सेवा व चिकित्सा)
- **फ़ील्ड्स:** गौशाला नाम, कुल गौवंश संख्या (उदा. 350 गायें), आवश्यकता (चारा, शेड, एम्बुलेंस, दवाइयां), पशु चिकित्सक का नाम व संपर्क।
- **अनिवार्य अपलोड्स:** 📸 बीमार/घायल गायों व गौशाला की फोटो, 📄 पशु चिकित्सक की रिपोर्ट व पर्चा, 🧾 चारा सप्लायर कोटेशन।

### 4. 🎓 Vidya Daan & Gurukul (विद्या दान व वेद विद्यालय)
- **फ़ील्ड्स:** गुरुकुल का नाम, मान्यता विवरण, बटुकों की संख्या (उदा. 75 बालक), आवश्यकता (शुल्क, वैदिक पुस्तकें, सात्विक भोजन, वस्त्र)।
- **अनिवार्य अपलोड्स:** 📄 गुरुकुल रजिस्ट्रेशन, 📸 बटुकों व कक्षाओं की फोटो, 🧾 वार्षिक खर्च ब्योरा।

### 5. 🛕 Mandir & Kund Heritage Restoration (प्राचीन मंदिर व कुंड जीर्णोद्धार)
- **फ़ील्ड्स:** मंदिर/कुंड का नाम, पौराणिक इतिहास, विग्रह, 84 कोस में स्थिति (उदा. नंदगांव, गोवर्धन), नुकसान का स्वरूप (टूटा शिखर, सूखा कुंड)।
- **अनिवार्य अपलोड्स:** 📸 खंडित मंदिर/कुंड की फोटो, 📄 ग्राम पंचायत / प्रबंध समिति की संस्तुति, 📑 शिल्पी/वास्तुकार का खर्च एस्टीमेट।

### 6. 🚨 Emergency Family Relief (आपदा व बेसहारा परिवार सहायता)
- **फ़ील्ड्स:** परिवार के मुखिया का नाम, आश्रित बच्चों/वृद्धों की संख्या, संकट का कारण (दुर्घटना, आकस्मिक मृत्यु, आग, बाढ़), तात्कालिक आवश्यकता।
- **अनिवार्य अपलोड्स:** 📄 मृत्यु प्रमाण पत्र / पुलिस FIR / ग्राम प्रधान पत्र, 📸 पीड़ित परिवार व क्षतिग्रस्त घर की वास्तविक फोटो।

---

## 💖 4. सार्वजनिक दानी सम्मान दीवार (Public Donors Wall Engine)

*दानियों के नाम और शहर को सार्वजनिक रूप से प्रदर्शित करने से पारदर्शिता बढ़ती है और अन्य लोगों को दान करने की प्रेरणा मिलती है:*

1. **लाइव दानी फीड (Live Donor Feed):**
   - दानी का नाम: `श्रीमती सुनीता शर्मा`
   - शहर व राज्य: `📍 जयपुर, राजस्थान`
   - दान राशि: `<span style="color:#16a34a;font-weight:700;">₹1,100</span>`
   - समय: `10 मिनट पहले`
   - दानी का मंगलकामना संदेश: *“ठाकुर जी आपको शीघ्र पूर्ण स्वस्थ करें, जय श्री राधे! 🌸”*
2. **गोपनीयता विकल्प (Anonymous Checkbox):**  
   यदि कोई गुप्त दान करना चाहे, तो टिक करते ही दिखेगा:  
   `एक श्रद्धालु • 📍 मुंबई, महाराष्ट्र • ₹501`
3. **मुख्य संरक्षक लीडरबोर्ड (Top Donors Leaderboard):**  
   अभियान के टॉप 3 दानियों को **"मुख्य जीवन रक्षक"** के रूप में शीर्ष पर स्वर्ण पदक के साथ दर्शाया जाएगा।
4. **1-Click WhatsApp वायरल शेयर कार्ड:**  
   मरीज की तस्वीर, प्रोग्रेस बार और त्वरित UPI QR के साथ व्हाट्सएप पर वायरल होने वाला स्वचालित इमेज कार्ड।

---

## 🗄️ 5. डेटाबेस स्कीमा (Database Architecture)

```sql
-- 1. campaigns table
CREATE TABLE `campaigns` (
  `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  `user_id` BIGINT UNSIGNED NOT NULL, -- Campaigner / Fundraiser User
  `category` ENUM('medical', 'trust', 'gau_seva', 'education', 'mandir', 'emergency') NOT NULL,
  `title` VARCHAR(255) NOT NULL,
  `slug` VARCHAR(255) UNIQUE NOT NULL,
  `target_amount` DECIMAL(12, 2) NOT NULL,
  `raised_amount` DECIMAL(12, 2) DEFAULT 0.00,
  `donors_count` INT UNSIGNED DEFAULT 0,
  `days_left` INT UNSIGNED DEFAULT 30,
  `end_date` DATE NULL,
  
  -- Media & Narrative
  `cover_banner` VARCHAR(255) NULL,
  `patient_photo` VARCHAR(255) NULL,
  `video_url` VARCHAR(255) NULL,
  `story` LONGTEXT NOT NULL,
  
  -- Category-Specific Dynamic Meta JSON (Patient name, Hospital, Doctor, Trust Darpan, etc.)
  `category_meta` JSON NULL,
  
  -- Payout Bank Details (Hospital / Trust direct)
  `beneficiary_name` VARCHAR(255) NOT NULL,
  `payout_type` ENUM('hospital_direct', 'trust_direct', 'beneficiary_personal') DEFAULT 'hospital_direct',
  `bank_name` VARCHAR(255) NULL,
  `account_number` VARCHAR(50) NULL,
  `ifsc_code` VARCHAR(20) NULL,
  `upi_id` VARCHAR(100) NULL,

  -- Admin Internal Financial Controls (Strictly Hidden from Public & Fundraiser)
  `admin_fee_percentage` DECIMAL(5, 2) DEFAULT 0.00, -- Case-to-case retention/management fee
  `admin_payout_notes` TEXT NULL,
  
  -- Verification & Publishing (ADMIN GATEKEEPER)
  `status` ENUM('draft', 'pending_review', 'active', 'goal_reached', 'completed', 'rejected') DEFAULT 'pending_review',
  `is_verified` BOOLEAN DEFAULT FALSE,
  `verified_at` DATETIME NULL,
  `verified_by_user_id` BIGINT UNSIGNED NULL,
  `verification_notes` TEXT NULL,
  `is_emergency` BOOLEAN DEFAULT FALSE,
  `is_featured_home` BOOLEAN DEFAULT FALSE,
  
  `created_at` TIMESTAMP NULL,
  `updated_at` TIMESTAMP NULL
);

-- 2. campaign_donations table
CREATE TABLE `campaign_donations` (
  `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  `campaign_id` BIGINT UNSIGNED NOT NULL,
  `user_id` BIGINT UNSIGNED NULL,
  `donor_name` VARCHAR(255) NOT NULL,
  `donor_email` VARCHAR(255) NOT NULL,
  `donor_phone` VARCHAR(20) NULL,
  `donor_city` VARCHAR(100) NULL,
  `donor_state` VARCHAR(100) NULL,
  `donor_country` VARCHAR(100) DEFAULT 'India',
  `amount` DECIMAL(10, 2) NOT NULL,
  `currency` VARCHAR(10) DEFAULT 'INR',
  `payment_id` VARCHAR(100) NULL,
  `payment_method` VARCHAR(50) NULL,
  `payment_status` ENUM('pending', 'completed', 'failed', 'refunded') DEFAULT 'completed',
  `donor_prayer` TEXT NULL,
  `is_anonymous` BOOLEAN DEFAULT FALSE,
  `is_80g_eligible` BOOLEAN DEFAULT FALSE,
  `receipt_number` VARCHAR(50) NULL,
  `created_at` TIMESTAMP NULL,
  `updated_at` TIMESTAMP NULL
);

-- 3. campaign_updates table
CREATE TABLE `campaign_updates` (
  `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  `campaign_id` BIGINT UNSIGNED NOT NULL,
  `title` VARCHAR(255) NOT NULL,
  `content` TEXT NOT NULL,
  `update_photo` VARCHAR(255) NULL,
  `created_at` TIMESTAMP NULL,
  `updated_at` TIMESTAMP NULL
);

-- 4. campaign_documents table (Proofs)
CREATE TABLE `campaign_documents` (
  `id` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  `campaign_id` BIGINT UNSIGNED NOT NULL,
  `doc_type` VARCHAR(100) NOT NULL,
  `doc_path` VARCHAR(255) NOT NULL,
  `is_public_visible` BOOLEAN DEFAULT TRUE,
  `created_at` TIMESTAMP NULL,
  `updated_at` TIMESTAMP NULL
);
```

---

## 💻 6. एडमिन मॉड्यूल (`/admin/campaigns`)

- **Exact Directory Listings Design Tokens:**
  - `.dir-head` with `+ Add New Campaign` (`.dir-btn-gold`).
  - `.dir-stats` KPI Cards: Total Campaigns, Pending Verification, Active Live, Total Raised (₹).
  - `.dir-toolbar`: सर्च बार + कैटेगरी फ़िल्टर (Medical, Trust, Gau Seva) + स्टेटस फ़िल्टर।
  - `.dir-table`: चेकबॉक्स, थंबनेल/पेशेंट फोटो, टाइटल, कैटेगरी, टारगेट vs कलेक्टेड प्रोग्रेस बार, स्थिति, और टूलटिप एक्शन बटन्स:
    - `👁️ View Live Campaign`
    - `✏️ Edit Campaign Details`
    - `🛡️ Quick Verify & Approve`
    - `❌ Reject Campaign`
    - `⭐ Feature on Homepage`
    - `🗑️ Delete Campaign`
- **Master-Detail Canvas Layout (`_form.blade.php`):**
  - बाएँ Sticky Menu (Step 1: Basis & Target, Step 2: Fundraiser User, Step 3: Dynamic Category Fields, Step 4: Hospital/Trust Bank Details, Step 5: Verification & Badges).

---

## 🌐 7. पब्लिक फ्रंटेंड व फंडरेज़र कंसोल

### पब्लिक राउट्स (`routes/web.php`):
- `GET /campaigns`: ऑल क्राउडफंडिंग हब (सर्च, फ़िल्टर, कैटेगरी चिप्स, इमरजेंसी टैब)।
- `GET /campaigns/{slug}`: कैंपेन डिटेल पेज (मरीज की कहानी, फोटो गैलरी, सत्यापित डॉक्यूमेंट्स, लाइव डोनर्स वॉल, UPI/Razorpay डोनेशन मोडल, और WhatsApp शेयर)।
- `POST /campaigns/{slug}/donate`: डोनेशन सबमिशन व रसीद जनरेशन।

### फंडरेज़र कंसोल राउट्स:
- `GET /fundraiser/register`: फंडरेज़र साइनअप।
- `GET /fundraiser/dashboard`: लाइव स्टेट्स (कुल प्राप्त दान, डोनर लिस्ट, विथड्रॉल स्थिति)।
- `GET /fundraiser/campaigns/create`: 4-स्टेप पब्लिक कैंपेन सबमिशन फॉर्म।
- `POST /fundraiser/campaigns/{id}/updates`: मरीज के स्वास्थ्य में सुधार का नया अपडेट व फोटो पोस्ट करना।

---

## 🚀 8. स्टेप-बाय-स्टेप विकास रोडमैप (Development Execution Roadmap)

| चरण (Phase) | कार्य (Task) | फाइलें (Files) | स्थिति |
| :--- | :--- | :--- | :--- |
| **Phase 1** | रोडमैप व नियम दस्तावेज़ निर्माण | `pages/crowdfunding.md` | ✅ पूर्ण |
| **Phase 2** | डेटाबेस माइग्रेशन | `database/migrations/xxxx_create_campaigns_and_crowdfunding_tables.php` | ⏳ तैयार |
| **Phase 3** | एलोक्वेंट मॉडल्स व रिलेशनशिप्स | `app/Models/Campaign.php`, `CampaignDonation.php`, `CampaignUpdate.php`, `CampaignDocument.php` | ⏳ तैयार |
| **Phase 4** | एडमिन कैंपेन प्रबंधन कंट्रोलर | `app/Http/Controllers/Admin/CampaignAdminController.php` | ⏳ तैयार |
| **Phase 5** | एडमिन व्यूज (Index, Create, Edit, _Form) | `resources/views/admin/campaigns/*` | ⏳ तैयार |
| **Phase 6** | पब्लिक कैंपेन कंट्रोलर व व्यू | `app/Http/Controllers/Frontend/CampaignController.php`, `resources/views/frontend/campaigns/*` | ⏳ तैयार |
| **Phase 7** | फ्रंटेंड फंडरेज़र कंसोल | `app/Http/Controllers/Frontend/FundraiserDashboardController.php`, `resources/views/frontend/fundraiser/*` | ⏳ तैयार |
| **Phase 8** | होमपेज क्राउडफंडिंग सेक्शन | `resources/views/frontend/home.blade.php` | ⏳ तैयार |
| **Phase 9** | एंड-टू-एंड ब्राउज़र टेस्टिंग | `tests/Feature/CrowdfundingEcosystemTest.php` + Browser Subagent | ⏳ तैयार |

---

*यह संपूर्ण दस्तावेज़ अब उत्पादन-स्तरीय (production-ready) विकास के लिए पूर्णतः तैयार है।*
