README

A modern, intelligent chat assistant for Laravel applications with automatic error detection, file attachments, and bilingual support.

🌟 Features

✅ Auto Error Detection - Automatically scans pages for errors
✅ Clickable Error Tags - Interactive chips for found errors
✅ Modern Chat UI - WhatsApp/ChatGPT-inspired design
✅ File Attachments - Upload images, PDFs, and documents
✅ Fullscreen Preview - View attachments in fullscreen modal
✅ Bilingual Support - English and Hindi responses
✅ Typing Indicators - Animated dots while waiting
✅ Smart Context - Includes error context in queries
✅ Responsive Design - Works on mobile and desktop
✅ Smooth Animations - Professional transitions and effects

📸 Screenshots

See the visual mockups showing the modern, premium design!

🚀 Quick Start

Installation

This package is already installed in your Laravel application.

Deployment

# Clear caches
php artisan cache:clear
php artisan view:clear

# Publish assets
php artisan vendor:publish --tag=smart-ai-assistant-assets --force
php artisan vendor:publish --tag=smart-ai-assistant-views --force

# Hard refresh browser
# Ctrl + Shift + R

Usage

Add the widget to any Blade template:

<x-smart-assistant-widget />

That's it! The assistant will appear as a floating button in the bottom-right corner.

📚 Documentation

Document	Description
UPGRADE_SUMMARY.md	Complete upgrade overview
DEPLOYMENT_GUIDE.md	Step-by-step deployment
README_UPGRADE.md	Feature documentation
ARCHITECTURE.md	System architecture
QUICK_REFERENCE.md	Developer quick reference
CHANGELOG.md	Version history

🎯 How It Works

1. Panel Opens

Shows welcome message: "Hello! I'm Soniya"
Automatically scans page for errors
Displays status: "Scanning your page..."

2. Error Detection

Scans for: .alert-danger, .invalid-feedback, .text-danger, .smart-error
Displays errors as clickable tags
Shows warning icon (⚠️)

3. User Interaction

Click error tag → Sends to API → Shows AI response
Or type manual message → Send to support
Attach files for context

4. AI Response

Returns English and Hindi solutions
Displays in chat bubble format
Auto-scrolls to bottom

🎨 Customization

Change Colors

Edit public/css/assistant.css:

#smart-assistant-toggle {
    background: linear-gradient(135deg, #YOUR_COLOR_1 0%, #YOUR_COLOR_2 100%);
}

Change Assistant Name

Edit resources/views/components/widget.blade.php:

<div class="sa-welcome-title">Hello! I'm YOUR_NAME</div>

Add Error Selectors

Edit public/js/assistant.js:

const errorSelectors = [
    '.alert-danger',
    '.your-custom-selector'
];

🔧 API Endpoints

Error Query

POST /smart-assistant/help

Request:

{
    "error_text": "Error message",
    "page_url": "https://example.com"
}

Response:

{
    "answer_en": "English solution",
    "answer_hi": "Hindi solution",
    "source": "known"
}

Chat Message

POST /customer-support/raise/ticket

FormData:

maddox_id: User ID
description: Message text
attachment: File (optional)

📁 File Structure

packages/smart-ai-assistant/
├── public/
│   ├── css/
│   │   └── assistant.css
│   └── js/
│       ├── ui-manager.js
│       ├── api-manager.js
│       ├── file-preview.js
│       └── assistant.js
├── resources/
│   └── views/
│       └── components/
│           └── widget.blade.php
├── src/
│   ├── Http/
│   │   └── Controllers/
│   ├── Models/
│   └── SmartAiAssistantServiceProvider.php
├── config/
│   └── smart-ai-assistant.php
├── database/
│   └── migrations/
└── routes/
    └── web.php

🧪 Testing

Manual Testing Checklist

Panel opens with welcome message
Error scanning detects errors
Error tags are clickable
Chat messages display correctly
File attachment works
Fullscreen preview opens
Send button works
API responses display
Mobile responsive works
No console errors

Browser Testing

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+
Mobile browsers

🐛 Troubleshooting

Changes not appearing?

Clear all Laravel caches
Republish assets with --force
Hard refresh browser

JavaScript errors?

Check all 4 JS files are loaded
Verify load order in widget.blade.php
Check browser console

Styles not applying?

Verify CSS file is loaded
Check for CSS conflicts
Inspect elements in DevTools

See DEPLOYMENT_GUIDE.md for more troubleshooting tips.

📊 Version History

v2.0.0 (2025-12-04)

Complete UI/UX overhaul
Modular JavaScript architecture
File attachment system
Fullscreen preview modal
Modern chat interface
Comprehensive documentation

v1.0.0 (2025-11-29)

Initial release
Basic error detection
Simple chat interface

See CHANGELOG.md for detailed history.

🏗️ Architecture

Modular Design

ui-manager.js - UI interactions and state
api-manager.js - Backend communications
file-preview.js - File handling and preview
assistant.js - Main controller

Data Flow

User Action → UI Manager → API Manager → Backend
                ↓              ↓
         Update UI ← Parse Response

See ARCHITECTURE.md for detailed diagrams.

🎓 Learning Resources

For Developers

Start with QUICK_REFERENCE.md
Study ARCHITECTURE.md
Review code comments in JS files

For Designers

Review assistant.css
Check color palette in docs
Inspect animations

For Testers

Follow testing checklist above
Test on multiple browsers
Test error scenarios

🤝 Contributing

This is a proprietary package for Maddox Pay. Internal contributions welcome.

Development Workflow

Make changes in packages/smart-ai-assistant/
Test locally
Publish assets
Test in browser
Document changes

📄 License

Proprietary - Maddox Pay

👥 Credits

Developed for: Maddox Pay
Version: 2.0.0
Last Updated: December 4, 2025

📞 Support

For issues or questions:

Check documentation files
Review troubleshooting section
Check browser console
Contact development team

🎯 Roadmap

Future Enhancements

Voice input support
Multi-language support (beyond EN/HI)
Advanced analytics
Custom themes
Keyboard shortcuts
Search history
Export chat history

🌟 Why Choose Smart AI Assistant?

Before

Basic error detection
Simple UI
Limited functionality
No file support
Minimal documentation

After (v2.0)

✅ Advanced error detection with tags
✅ Modern, premium UI
✅ Full file attachment system
✅ Fullscreen previews
✅ Comprehensive documentation
✅ Mobile responsive
✅ Smooth animations
✅ Bilingual support

Ready to get started? Check out DEPLOYMENT_GUIDE.md!

subodh / smart-ai-assistant

Maintainers

Package info

Statistics

Security