🚀 Mercury CRM - Developer Documentation

Welcome to Mercury CRM, a powerful and scalable Customer Relationship Management system built with modern web technologies. This documentation will guide you through every aspect of our application, from initial setup to advanced customization.

🎯 What is Mercury CRM?

Mercury CRM is a comprehensive business solution featuring:

• 🏗️ HMVC Architecture - Modular, scalable, and maintainable codebase
• 📱 WhatsApp Integration - Advanced Waha module for business communication
• ☁️ Cloud Storage - Seamless AWS S3 integration
• 📊 Advanced Analytics - Real-time insights and reporting
• 🔒 Enterprise Security - Multi-layer authentication and authorization
• 🌐 Multi-tenant Support - Scalable for businesses of all sizes

⚡ Quick Start

Get up and running in 5 minutes:

# 1. Clone the repository
git clone <repository-url>
cd mercury-crm

# 2. Install dependencies
composer install
npm install

# 3. Setup environment
cp .env.example .env
php artisan key:generate

# 4. Run migrations
php artisan migrate --seed

# 5. Start development server
php artisan serve

💡 Tip: For detailed installation instructions, see our Installation Guide

📖 Documentation Sections

🏁 Getting Started

• Installation Guide - Complete setup instructions
• HMVC Architecture - Understanding our modular approach
• Project Structure - Code organization and patterns

📋 Core Modules

• Lead Module - CRM lead management with clean architecture ⭐

🏛️ Architecture & Design

• Waha Module - WhatsApp integration architecture
• S3 Storage Service - File management and cloud storage
• Database Design - Schema patterns and relationships

⚙️ Configuration & Services

• Environment Setup - Configuration management
• API Documentation - RESTful API reference
• Authentication - Security and access control

🏗️ System Architecture

Our system follows an API-first architecture with clear separation between frontend and backend:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   API Gateway   │    │   Backend       │
│   (Next.js)     │◄──►│   (Laravel)     │◄──►│   (HMVC)        │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                 │
                        ┌─────────────────┐
                        │   Services      │
                        │   • Waha        │
                        │   • S3 Storage  │
                        │   • Analytics   │
                        │   • Notifications│
                        └─────────────────┘

API-First Design

• Backend: Laravel provides RESTful APIs with JWT authentication
• Frontend: Next.js consumes APIs independently
• Documentation: Interactive Swagger docs at /docs/admin and /docs/instructor
• Modularity: Each service can be developed and deployed independently

🛠️ Technology Stack

Backend

• PHP 8.4+ - Modern PHP with type declarations
• Laravel 11 - Robust framework with advanced features
• MySQL 8.0 - High-performance database
• Redis - Caching and session management

Frontend

• Next.js - React-based full-stack framework
• React - Component-based UI library
• TypeScript - Type-safe JavaScript development

Infrastructure

• Docker - Containerized development environment
• AWS S3 - Scalable file storage
• WhatsApp API - Business communication platform

📁 Module Overview

Our HMVC architecture consists of several specialized modules:

🚀 Development Workflow

1. Feature Development

# Create feature branch
git checkout -b feature/new-feature

# Development workflow
composer install
npm run dev
php artisan serve

# Run tests
php artisan test
npm run test

2. Code Standards

• PSR-12 coding standards
• Type declarations for all methods
• PHPDoc documentation
• Unit & Feature tests for all new code

3. Module Creation

# Generate new module
php artisan module:make ModuleName

# Generate module components
php artisan module:make-controller ModuleName ControllerName
php artisan module:make-model ModuleName ModelName
php artisan module:make-migration ModuleName create_table_name

🔐 Security Features

• 🛡️ Authentication - Multi-factor authentication support
• 🔑 Authorization - Role-based access control (RBAC)
• 🔒 Data Encryption - End-to-end encryption for sensitive data
• 🌐 API Security - JWT tokens and rate limiting
• 📋 Audit Logging - Comprehensive activity tracking

📊 Performance & Monitoring

• ⚡ Caching - Redis-based caching strategy
• 📈 Monitoring - Application performance metrics
• 🔍 Logging - Structured logging with context
• 📱 Real-time - WebSocket support for live updates

🧪 Testing Strategy

# Run all tests
php artisan test

# Run specific test suite
php artisan test --testsuite=Unit
php artisan test --testsuite=Feature

# Generate coverage report
php artisan test --coverage

Testing Levels

• Unit Tests - Individual component testing
• Feature Tests - End-to-end workflow testing
• Integration Tests - Module interaction testing

🚀 Deployment

Production Deployment

# Production optimization
composer install --no-dev --optimize-autoloader
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Database migrations
php artisan migrate --force

# Queue processing
php artisan queue:work --daemon

Environment Requirements

• PHP 8.4+ with required extensions
• MySQL 8.0+ or PostgreSQL 13+
• Redis 6.0+ for caching
• Node.js 16+ for asset compilation

🤝 Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Follow our coding standards
4. Write comprehensive tests
5. Submit a pull request

Development Setup

# Clone your fork
git clone <your-fork-url>
cd mercury-crm

# Install dependencies
composer install
npm install

# Setup development environment
./setup-dev.sh

📞 Support & Resources

Getting Help

• 📖 Documentation - Comprehensive guides and examples
• 🐛 Issues - Report bugs and request features
• 💬 Discussions - Community Q&A and ideas
• 📧 Contact - Direct support for enterprise users

Useful Links

• API Documentation - Interactive API explorer
• Architecture Guide - Deep dive into our HMVC pattern
• Deployment Guide - Production deployment strategies
• Troubleshooting - Common issues and solutions

🗺️ Roadmap

Current Version (v2.0)

• ✅ HMVC Architecture
• ✅ Waha WhatsApp Integration
• ✅ S3 File Management
• ✅ Advanced Authentication

Upcoming Features

• 🔄 GraphQL API - Modern API architecture
• 📱 Mobile App - Native mobile applications
• 🤖 AI Integration - Intelligent automation
• 📊 Advanced Analytics - Business intelligence tools

🎉 Ready to Build?

Choose your path:

💡 Pro Tip: Our documentation is interactive! Use the search feature to quickly find what you need, and don't forget to check out our Swagger API documentation for hands-on API testing.

Built with ❤️ by the Mercury CRM Team