╔══════════════════════════════════════════════════════════════════════════════╗
║                  📢 NOTIFICATIONS API - VISUAL GUIDE                         ║
╚══════════════════════════════════════════════════════════════════════════════╝

┌──────────────────────────────────────────────────────────────────────────────┐
│ API ENDPOINTS TREE                                                           │
└──────────────────────────────────────────────────────────────────────────────┘

/api/
├── 📄 notifications/
│   ├── GET → List all notifications (paginated: 6 per page)
│   │   ├── ?page=2
│   │   ├── ?page_size=10
│   │   ├── ?category=Admissions
│   │   ├── ?priority=high
│   │   ├── ?featured=true
│   │   └── ?search=admission
│   │
│   └── {slug}/
│       └── GET → Get notification details (full content, tags, attachment)
│
├── 🌟 featured-notifications/
│   └── GET → Get top 6 featured notifications only
│
├── 🏷️  notification-tags/
│   ├── GET → List all tags (paginated)
│   │   └── ?search=important
│   │
│   └── {id}/
│       └── GET → Get specific tag details
│
├── 📂 notification-categories/
│   └── GET → List all categories with color codes
│
├── 📊 statistics/
│   └── GET → List site statistics (students, faculty, etc.)
│
└── 🔗 notifications-and-stats/
    └── GET → Combined: notifications + statistics + pagination
        (Best for homepage)


┌──────────────────────────────────────────────────────────────────────────────┐
│ QUICK START - TOP 3 ENDPOINTS                                               │
└──────────────────────────────────────────────────────────────────────────────┘

1️⃣  GET ALL NOTIFICATIONS (with pagination)
    curl "https://api-cmshu.surl.co.in/api/notifications/"
    └─ Returns: Array with 6 items + pagination info

2️⃣  GET FEATURED + STATS (Homepage)
    curl "https://api-cmshu.surl.co.in/api/notifications-and-stats/"
    └─ Returns: Featured notifications + statistics + pagination

3️⃣  GET NOTIFICATION DETAIL
    curl "https://api-cmshu.surl.co.in/api/notifications/admission-portal-open/"
    └─ Returns: Full notification with HTML content + tags + attachment


┌──────────────────────────────────────────────────────────────────────────────┐
│ RESPONSE STRUCTURE                                                           │
└──────────────────────────────────────────────────────────────────────────────┘

LIST ENDPOINT (Paginated)
{
  "count": 15,          // Total items in database
  "next": "?page=2",    // Link to next page (or null)
  "previous": null,     // Link to previous page (or null)
  "results": [          // Array of items
    { ... }
  ]
}

DETAIL ENDPOINT
{
  "id": 1,
  "title": "...",
  "content": "<p>HTML...</p>",
  "tags": [
    { "id": 1, "name": "important" },
    { "id": 2, "name": "admissions" }
  ],
  "category": {
    "id": 1,
    "name": "Admissions",
    "color_code": "#61b239"
  },
  "attachment": "https://example.com/file.pdf",
  "external_link": "https://example.com"
}

FEATURED ENDPOINT (Array)
[
  { notification_1 },
  { notification_2 },
  ...
]


┌──────────────────────────────────────────────────────────────────────────────┐
│ FILTERING & SEARCH                                                           │
└──────────────────────────────────────────────────────────────────────────────┘

FILTER BY PRIORITY
  ?priority=low
  ?priority=medium
  ?priority=high
  ?priority=urgent

FILTER BY CATEGORY
  ?category=Admissions
  ?category=Careers
  ?category=Scholarships

FILTER BY FEATURED
  ?featured=true        (only featured)
  ?featured=false       (exclude featured)

SEARCH
  ?search=admission     (in title, description, content)

PAGINATION
  ?page=1               (page number)
  ?page_size=10         (items per page, default 6, max 50)

COMBINE FILTERS
  ?category=Admissions&priority=high&page=2&page_size=10


┌──────────────────────────────────────────────────────────────────────────────┐
│ COMMON USE CASES                                                             │
└──────────────────────────────────────────────────────────────────────────────┘

HOME PAGE
  GET /api/notifications-and-stats/
  └─ Shows featured notifications + key statistics

NEWS LIST PAGE
  GET /api/notifications/?page=1
  └─ All notifications with pagination

SINGLE NEWS DETAIL
  GET https://api-cmshu.surl.co.in/api/notifications/admission-portal-open/
  └─ Full content, tags, attachment

FILTER BY CATEGORY
  GET https://api-cmshu.surl.co.in/api/notifications/?category=Admissions
  └─ All admissions-related notifications

URGENT ONLY
  GET https://api-cmshu.surl.co.in/api/notifications/?priority=urgent
  └─ Only urgent notifications

SEARCH
  GET https://api-cmshu.surl.co.in/api/notifications/?search=scholarship
  └─ Search across all fields

GET TAGS
  GET https://api-cmshu.surl.co.in/api/notification-tags/
  └─ For tag filters/display

GET CATEGORIES
  GET https://api-cmshu.surl.co.in/api/notification-categories/
  └─ For category filters/display


┌──────────────────────────────────────────────────────────────────────────────┐
│ NOTIFICATION OBJECT STRUCTURE                                               │
└──────────────────────────────────────────────────────────────────────────────┘

{
  "id": 1,                              // Unique identifier
  "title": "Admission Portal Open",     // Main title
  "slug": "admission-portal-open",      // URL-friendly identifier
  "description": "Short description",   // Summary/excerpt
  "content": "<p>Full HTML...</p>",     // Full content (HTML)
  
  "category": {                         // Category object
    "id": 1,
    "name": "Admissions",
    "color_code": "#61b239"
  },
  
  "priority": "high",                   // low/medium/high/urgent
  "is_featured": true,                  // Show in featured section
  "is_active": true,                    // Published/unpublished
  
  "published_date": "2025-12-10T10:30:00Z",  // Publication time
  "created_at": "2025-12-10T08:00:00Z",     // Created timestamp
  "updated_at": "2025-12-10T10:30:00Z",     // Last updated timestamp
  
  "date": {                             // Formatted date object
    "day": "10",
    "month": "December",
    "year": "2025",
    "full_date": "2025-12-10",
    "iso_date": "2025-12-10T10:30:00Z"
  },
  
  "external_link": "https://...",       // Related link (optional)
  "attachment": "https://.../file.pdf", // File attachment (optional)
  "meta_description": "SEO...",         // Meta description
  
  "tags": [                             // Associated tags
    { "id": 1, "name": "important" },
    { "id": 2, "name": "admissions" }
  ]
}


┌──────────────────────────────────────────────────────────────────────────────┐
│ JAVASCRIPT/FETCH EXAMPLES                                                   │
└──────────────────────────────────────────────────────────────────────────────┘

// Get all notifications
fetch('/api/notifications/')
  .then(r => r.json())
  .then(data => console.log(data.results))

// Get featured + stats
fetch('/api/notifications-and-stats/')
  .then(r => r.json())
  .then(data => {
    data.notifications  // Featured notifications
    data.statistics     // Site statistics
    data.pagination     // Pagination info
  })

// Get specific notification
fetch('https://api-cmshu.surl.co.in/api/notifications/admission-portal-open/')
  .then(r => r.json())
  .then(notification => console.log(notification))

// Search
fetch('https://api-cmshu.surl.co.in/api/notifications/?search=admission')
  .then(r => r.json())
  .then(data => console.log(data.results))

// Get all tags
fetch('https://api-cmshu.surl.co.in/api/notification-tags/')
  .then(r => r.json())
  .then(data => console.log(data.results))

// Get categories
fetch('https://api-cmshu.surl.co.in/api/notification-categories/')
  .then(r => r.json())
  .then(data => console.log(data))


┌──────────────────────────────────────────────────────────────────────────────┐
│ ERROR CODES                                                                  │
└──────────────────────────────────────────────────────────────────────────────┘

200 OK
  ✓ Request successful

400 BAD REQUEST
  ✗ Invalid parameters or malformed request

404 NOT FOUND
  ✗ Notification/tag/category does not exist

500 SERVER ERROR
  ✗ Server-side error


┌──────────────────────────────────────────────────────────────────────────────┐
│ KEY FEATURES                                                                 │
└──────────────────────────────────────────────────────────────────────────────┘

✅ Read-Only         → GET requests only (safe API)
✅ Pagination        → Handle large datasets
✅ Search            → Full-text search
✅ Filtering         → Multiple filter options
✅ Rich Content      → HTML support
✅ Attachments       → File support
✅ Tags              → Multiple tags per item
✅ Categories        → Color-coded categories
✅ Statistics        → KPI display
✅ Featured Items    → Homepage highlights
✅ Date Formatting   → Multiple date formats
✅ Performance       → Optimized queries


┌──────────────────────────────────────────────────────────────────────────────┐
│ DOCUMENTATION FILES                                                          │
└──────────────────────────────────────────────────────────────────────────────┘

📄 NOTIFICATIONS_API_DOCUMENTATION.md
   → Comprehensive guide with all endpoints and JSON samples

📘 NOTIFICATIONS_API_QUICK_REFERENCE.md
   → Quick lookup for common tasks

📊 NOTIFICATIONS_API_SUMMARY.md
   → Complete overview with models and use cases

📺 NOTIFICATIONS_API_VISUAL_GUIDE.txt
   → This file (visual reference)

═══════════════════════════════════════════════════════════════════════════════
Last Updated: December 10, 2025
═══════════════════════════════════════════════════════════════════════════════