# 📜 Dham Seva — Devotee Blogger & Author Ecosystem
## Complete Architecture & Implementation Roadmap (`blogger.md`)

> **UI/UX Consistency Law:**  
> The entire Blogger Studio, Profile Canvas, and Article Editor will strictly follow the **exact same UI/UX design language** as the **Business Listing Canvas** (`_form.blade.php`):
> - **Brand Theme & Accents:** Golden saffron gradients (`linear-gradient(135deg, #F2B622, #AC6106)`), `var(--bg-card)`, `var(--border)`, `var(--text-primary)`, `var(--text-secondary)`.
> - **Canvas Layout:** Left vertical step navigation menu (Setup Canvas) + Right multi-section card panels.
> - **Input Design:** Clean rounded inputs (`border-radius: 10px`), dashed gold upload dropzones (`border: 1.5px dashed #F2B622`), action pills, and status badges.
> - **Zero Extra Frames:** No foreign frameworks or mismatched design. 100% native Dham Seva tokens.

---

## 🏛️ 1. Core Principles & Business Logic

1. **100% Dynamic — Zero Hardcoding:**
   - Every blogger has full liberty to change their **Cover Banner**, **Profile Avatar**, **Bio**, **Spiritual Title**, **Social Links**, and **Pinned Spotlight Article** at any time.
2. **Social Vanity Handle (`@username`):**
   - Clean, memorable vanity URL for every author:
     - Profile: `dhamseva.com/@username` (or `dhamseva.com/author/@username`)
     - Article: `dhamseva.com/@username/{article-slug}`
3. **Controlled Sacred Taxonomy & Whitelist (पवित्रता व मर्यादा):**
   - Bloggers can only write on approved Sanatan Braj themes. No adult, political, vulgar, or unverified content.
   - Built-in real-time profanity and inappropriate keyword filter.
4. **Controlled Geography & Missing Location Request Engine:**
   - Articles must be anchored to our verified database: **Country → State → City / Locality → Place**.
   - If a blogger wants to write about a holy City, State, or Place not yet in our database, they click **"➕ Request New Location / City"**. Admin reviews and approves it in 1-click, making it instantly selectable.
5. **Support & Seva Donation Integration (दान / सेवा सहयोग):**
   - Devotees can support the author's writing and the sacred mission of Dham Seva directly via an interactive modal (`₹101`, `₹251`, `₹501`, `₹1100`, Custom).
   - Fully connected to Dham Seva's existing `DonationService` (UPI QR, NetBanking, 80G tax receipt).
   - Author dashboard reflects **"Total Seva Inspired by Your Writings (प्रेरित सेवा सहयोग)"** with reader gratitude notes.
6. **🔒 In-Platform Offline Reading (No Device File Downloads):**
   - Readers can click **"👜 तीर्थ झोले में सहेजें (Save to Offline Bag)"**.
   - Article is cached inside the web application via Service Worker / Cache Storage.
   - Yatris can read it anywhere in Braj without internet, but raw files cannot be exported or downloaded to their personal phone storage.

---

## 📚 2. The 8 Sacred Subject Categories

When creating a new article, the blogger selects from these 8 approved subjects:

1. **🛕 1. मंदिर व दिव्य दर्शन (Temples & Darshan):**
   - Mandir history, deity appearance, daily seva, shringar tradition, and aarti timings (linked to our verified Temples).
2. **🧘‍♂️ 2. संत, आचार्य व भक्त चरित्र (Saints & Acharya Biographies):**
   - Life stories of Braj saints: Swami Haridas, Surdas, Raskhan, Mirabai, Chaitanya Mahaprabhu, Shad Goswamis, Hit Harivansh Mahaprabhu.
3. **📜 3. ब्रज की प्राचीन लीला कथाएँ (Sacred Leela Kathas):**
   - Puranic stories based on Srimad Bhagavatam and Garga Samhita (Cheer Ghat, Maharaas, Kalia Daman, Makhan Chori, Govardhan Leela).
4. **🎉 4. ब्रज के पावन उत्सव व मेले (Festivals & Celebrations):**
   - Barsana Lathmar Holi, Phool Dol, Jhulanotsav, Sharad Purnima, Govardhan Annakut, Radhashtami, Janmashtami (linked to Festival calendar).
5. **🌊 5. पवित्र घाट, कुंड व सरोवर (Ghats, Kunds & Groves):**
   - Yamuna 24 Ghats, Radha Kund, Shyam Kund, Mansi Ganga, Kusum Sarovar, Nidhivan, Seva Kunj (bathing rules, significance).
6. **🚶‍♂️ 6. परिक्रमा मार्गदर्शिका (Parikrama & Yatra Guides):**
   - Govardhan (21 km), Vrindavan (10 km), Mathura, and 84 Kos Braj Parikrama guides, halts, rules, and caution tips.
7. **🌸 7. भक्तों के साक्षात अनुभव (Devotee Darshan Experiences):**
   - Real spiritual experiences of pilgrims visiting Braj and receiving divine grace.
8. **🥣 8. ब्रज संस्कृति, महाप्रसाद व गौ सेवा (Braj Heritage & Gau Seva):**
   - Chhappan Bhog, Makhan-Mishri, Peda, Desi Gau Seva, Braj Bhasha, and the spiritual sanctity of Braj Raj (sacred dust).

---

## 🎨 3. UI/UX Structure — Mirrored from Business Listing Canvas

### A. Blogger Studio Canvas (Left Navigation + Right Panels)
Just like the 13-step Business Listing Setup Canvas, the Blogger Studio uses a clean tabbed canvas:

| Step # | Canvas Step Title | Subtitle Hint | Key Inputs & Functions |
|---|---|---|---|
| **Step 1** | **👤 Identity & Handle** | Name, @username & Title | • Public Name<br>• Unique Vanity Handle (`@username`)<br>• Spiritual Title (e.g., *ब्रज अनुरागी*, *कथा वाचक*)<br>• Seva Category badge |
| **Step 2** | **🖼️ Banner & Avatar** | Custom Media Vault | • **Cover Banner Upload** (1200x400 dropzone with live preview)<br>• **Circular Avatar Upload** (with auto-crop)<br>• Default fallback to Divine Braj Sunset Banner |
| **Step 3** | **📍 Geography & Base** | Country, State, City | • Cascading selection: Country → State → City / Locality<br>• Primary Ashram / Residence location<br>• **"➕ Request Missing Location"** button |
| **Step 4** | **📖 Bio & Spiritual Journey** | Author Story & Socials | • Rich About Bio (English / Devanagari)<br>• Social handles: YouTube, Instagram, WhatsApp Channel, Facebook, Website |
| **Step 5** | **✍️ Article Studio** | Write, Format & Tag | • Subject Type selector (8 Sacred Categories)<br>• Target Place / Temple / Festival linker<br>• Rich Article Editor (Headings, quotes, images)<br>• Optional 1-3 min Audio Katha upload (`.mp3`)<br>• Photo Gallery upload (up to 10 images) |
| **Step 6** | **📌 Spotlight & Pinning** | Featured Article Selection | • Choose which article stays pinned at the top of the public profile |
| **Step 7** | **📊 Seva & Analytics** | Stats, Likes & Donations | • Total Reads, Total Hearts, Total Followers<br>• **Total Seva Inspired (प्रेरित सेवा सहयोग)**<br>• Reader Gratitude messages ledger |

---

### B. Public Profile Layout (`dhamseva.com/@username`)
```
+---------------------------------------------------------------------------------------------------------+
| [ 🌅 DYNAMIC BANNER IMAGE (1200x400) — Uploaded & Managed by Blogger with Divine Fallback ]             |
+---------------------------------------------------------------------------------------------------------+
|                                                                                                         |
|   [📷 AVATAR]   पं. रमेश शास्त्री  ⭐ [सत्यापित विद्वान बैज]                                              |
|   (Customized)  @shastriji  ·  "श्री राधा कृपा पात्र · 15 वर्षों से ब्रज लीला व तीर्थ अन्वेषक"               |
|                 📍 वृन्दावन, मथुरा   |  🔗 [YouTube] [Instagram] [WhatsApp Channel]                       |
|                                                                                                         |
|       [ 🔔 Subscribe (Follow) ]     [ 🙏 प्रणाम व सेवा सहयोग (Donate) ]     [ 📲 WhatsApp Share ]          |
|                                                                                                         |
+---------------------------------------------------------------------------------------------------------+
|  📊 24 प्रकाशित लेख   |   ❤️ 3,850 लाइक्स   |   👁️ 42,000 पाठक   |   👥 850 सब्सक्राइबर्स   |   🌸 ₹14,200 सेवा सहयोग  |
+---------------------------------------------------------------------------------------------------------+
|  नेविगेशन टैब्स: [⭐ सभी लेख (24)]  [🛕 मंदिर दर्शन (8)]  [📜 लीला कथाएँ (7)]  [🚶 परिक्रमा (4)]  [🌊 घाट व कुंड (3)]    |
+---------------------------------------------------------------------------------------------------------+
|  LEFT (2/3 भाग):                                        |  RIGHT (1/3 साइडबार):                          |
|  📌 PINNED ARTICLE (लेखक का पसंदीदा मुख्य लेख):         |  📖 लेखक का परिचय (About the Author)           |
|  +---------------------------------------------------+  |  "राधे-राधे! मैं पिछले 15 वर्षों से ब्रज      |
|  | [Cover Image]                                     |  |   के अनछुए तीर्थों और प्राचीन लीला स्थलों     |
|  | 🏷️ लीला कथा · ⏱️ 5 मिनट पठन · 📅 18 Nov             |  |   का अन्वेषण कर रहा हूँ..."                   |
|  | बांके बिहारी जी के प्राकट्य का रहस्य एवं संगीत सेवा   |  |                                               |
|  | ❤️ 420 लाइक्स  ·  💬 38 टिप्पणियाँ  ·  📲 शेयर     |  |  🏆 सेवा सम्मान बैज (Seva Badges):            |
|  | [ 👜 तीर्थ झोले में सहेजें (In-App Offline) ]        |  |  🥇 ब्रज साहित्यकार (15+ लेख)                  |
|  +---------------------------------------------------+  |  🌟 प्रमाणित कथावाचक (Verified)               |
|                                                         |                                               |
|  REGULAR BLOG CARDS (2-कॉलम ग्रिड):                     |  🌸 सेवा सहयोग कार्ड (Support Cause Box):       |
|  [थंबनेल · टाइटल · 2 लाइन सार · लाइक्स · कमेंट्स]         |     "लेखक की लेखनी से प्रेरित होकर ब्रज        |
|                                                         |      साधु व गौ सेवा में सहयोग करें"            |
|                                                         |     [ ₹101 ] [ ₹251 ] [ ₹501 ] [ अन्य ]         |
|                                                         |  📍 जुड़े हुए प्रमुख मंदिर (Tagged Places)     |
+---------------------------------------------------------------------------------------------------------+
```

---

## 🗄️ 4. Database Schema Design (Zero Hardcoding)

```sql
-- 1. Extend users table for Blogger / Author profile
ALTER TABLE users ADD COLUMN username VARCHAR(50) UNIQUE NULL AFTER name;
ALTER TABLE users ADD COLUMN author_title VARCHAR(150) NULL;
ALTER TABLE users ADD COLUMN author_bio TEXT NULL;
ALTER TABLE users ADD COLUMN author_banner VARCHAR(255) NULL;
ALTER TABLE users ADD COLUMN author_avatar VARCHAR(255) NULL;
ALTER TABLE users ADD COLUMN author_social_links JSON NULL;
ALTER TABLE users ADD COLUMN author_badge VARCHAR(50) DEFAULT 'pilgrim';
ALTER TABLE users ADD COLUMN pinned_article_id BIGINT UNSIGNED NULL;
ALTER TABLE users ADD COLUMN total_subscribers INT UNSIGNED DEFAULT 0;
ALTER TABLE users ADD COLUMN total_likes_received INT UNSIGNED DEFAULT 0;
ALTER TABLE users ADD COLUMN total_seva_inspired DECIMAL(12,2) DEFAULT 0.00;

-- 2. Articles / Devotee Blogs Table
CREATE TABLE articles (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    user_id BIGINT UNSIGNED NOT NULL,
    title VARCHAR(255) NOT NULL,
    slug VARCHAR(255) NOT NULL UNIQUE,
    subject_type ENUM('temple', 'saint', 'leela', 'festival', 'kund_ghat', 'parikrama', 'experience', 'heritage') NOT NULL,
    country_id BIGINT UNSIGNED NULL,
    state_id BIGINT UNSIGNED NULL,
    city_id BIGINT UNSIGNED NULL,
    place_id BIGINT UNSIGNED NULL,
    summary VARCHAR(500) NULL,
    content LONGTEXT NOT NULL,
    cover_image VARCHAR(255) NULL,
    gallery_images JSON NULL,
    audio_katha_url VARCHAR(255) NULL,
    reading_time VARCHAR(20) DEFAULT '3 min read',
    status ENUM('draft', 'pending_review', 'published', 'rejected') DEFAULT 'draft',
    views_count INT UNSIGNED DEFAULT 0,
    likes_count INT UNSIGNED DEFAULT 0,
    comments_count INT UNSIGNED DEFAULT 0,
    published_at TIMESTAMP NULL,
    created_at TIMESTAMP NULL,
    updated_at TIMESTAMP NULL,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

-- 3. Location / City Requests by Bloggers
CREATE TABLE location_requests (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    user_id BIGINT UNSIGNED NOT NULL,
    country_id BIGINT UNSIGNED NULL,
    state_name VARCHAR(150) NOT NULL,
    city_name VARCHAR(150) NOT NULL,
    place_name VARCHAR(255) NULL,
    significance_note TEXT NULL,
    status ENUM('pending', 'approved', 'rejected') DEFAULT 'pending',
    admin_notes TEXT NULL,
    created_at TIMESTAMP NULL,
    updated_at TIMESTAMP NULL,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

-- 4. Article Likes Table (With IP / User deduplication)
CREATE TABLE article_likes (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    article_id BIGINT UNSIGNED NOT NULL,
    user_id BIGINT UNSIGNED NULL,
    ip_hash VARCHAR(64) NOT NULL,
    created_at TIMESTAMP NULL,
    FOREIGN KEY (article_id) REFERENCES articles(id) ON DELETE CASCADE,
    UNIQUE KEY (article_id, ip_hash)
);

-- 5. Article Comments Table (With Author Reply Badge)
CREATE TABLE article_comments (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    article_id BIGINT UNSIGNED NOT NULL,
    user_id BIGINT UNSIGNED NULL,
    guest_name VARCHAR(100) NULL,
    comment_text TEXT NOT NULL,
    parent_id BIGINT UNSIGNED NULL,
    status ENUM('approved', 'pending', 'spam') DEFAULT 'approved',
    created_at TIMESTAMP NULL,
    updated_at TIMESTAMP NULL,
    FOREIGN KEY (article_id) REFERENCES articles(id) ON DELETE CASCADE,
    FOREIGN KEY (parent_id) REFERENCES article_comments(id) ON DELETE CASCADE
);

-- 6. Author Subscriptions Table
CREATE TABLE author_subscriptions (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    author_id BIGINT UNSIGNED NOT NULL,
    subscriber_user_id BIGINT UNSIGNED NULL,
    subscriber_email VARCHAR(255) NULL,
    subscriber_phone VARCHAR(20) NULL,
    is_active BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP NULL,
    FOREIGN KEY (author_id) REFERENCES users(id) ON DELETE CASCADE
);

-- 7. Add Author Attribution to Donations
ALTER TABLE donations ADD COLUMN referred_by_author_id BIGINT UNSIGNED NULL;
ALTER TABLE donations ADD COLUMN referred_by_article_id BIGINT UNSIGNED NULL;
ALTER TABLE donations ADD COLUMN donor_message TEXT NULL;
```

---

## 🗺️ 5. Step-by-Step Implementation Sequence

```mermaid
flowchart LR
    Step1["Step 1: DB Migrations & Models"] --> Step2["Step 2: Handle Routing (@username)"]
    Step2 --> Step3["Step 3: Blogger Studio Canvas"]
    Step3 --> Step4["Step 4: Location Request Flow"]
    Step4 --> Step5["Step 5: Public Profile Page"]
    Step5 --> Step6["Step 6: Seva Donation Modal"]
    Step6 --> Step7["Step 7: In-App Offline Bag"]
```

### 🔹 Step 1: Database Migrations & Eloquent Models
- Run migrations for `users` extension (`username`, `author_banner`, `author_avatar`, `author_bio`, `author_title`, `author_social_links`).
- Create `articles`, `location_requests`, `article_likes`, `article_comments`, `author_subscriptions` tables.
- Update `donations` table with author attribution fields.
- Set up relationships in `User.php`, `Article.php`, `Donation.php`.

### 🔹 Step 2: Vanity Handle Routing Engine
- In `routes/web.php`:
  - `/@{username}` → Maps directly to `AuthorProfileController@show`.
  - `/@{username}/{slug}` → Maps to `AuthorProfileController@showArticle`.
  - Fallback check ensures no collision with reserved routes (`/admin`, `/login`, etc.).

### 🔹 Step 3: Blogger Studio Canvas (Mirrored from Business Listing)
- Accessible at `/blogger/studio`.
- Identical left setup canvas menu + right multi-card panels with gold gradient buttons.
- Drag-and-drop Banner and Avatar upload dropzones (`border: 1.5px dashed #F2B622`).
- 8-Subject selector with cascading Country → State → City → Place dropdowns.
- Rich-text editor with Devanagari Hindi font support, audio katha upload, and image gallery.

### 🔹 Step 4: Missing Location Request Engine
- In the Geography selector, a prominent **"➕ Request New Location / City"** button opens a clean modal.
- Stores request into `location_requests` table.
- Admin Panel under `/admin/location-requests` has a 1-click **"Approve & Add to Places"** action.

### 🔹 Step 5: Public Author Profile Page (`/@username`)
- Exact matching color palette, cards, and typography.
- Hero Cover Banner (1200x400) + overlapping circular avatar with verified badge.
- Live stats bar: Articles, Hearts, Reads, Followers, Seva Inspired.
- Category filter navigation tabs.
- Pinned Spotlight Card + 2-column responsive article card grid.

### 🔹 Step 6: "Support Author & Seva Donation" Modal
- Clicking **"🙏 प्रणाम व सेवा सहयोग"** opens the spiritual modal.
- Pre-filled options (`₹101`, `₹251`, `₹501`, `₹1100`).
- Seva cause choice: Sadhu Seva, Gau Seva, Dham Seva.
- Direct seamless integration into `DonationService`.
- Real-time update of author's `total_seva_inspired` metric.

### 🔹 Step 7: In-Platform Offline Bag (तीर्थ झोला)
- Reader clicks **"👜 तीर्थ झोले में सहेजें"** on any article.
- Stored safely in Service Worker / IndexedDB cache.
- Accessible offline within the Dham Seva web app without raw file download to phone storage.

---

## 🎯 6. Status & Readiness

This blueprint (`blogger.md`) is completely detailed, consistent with the Business Listing UI/UX design tokens, and ready for execution.
