add mintlify intro docs

2025-05-28 23:42:34 +05:30
parent b5ebc47637
commit f429db89b4
19 changed files with 10055 additions and 1 deletions
@@ -0,0 +1,342 @@
+---
+title: Chatwoot Architecture
+description: Understanding Chatwoot's system architecture, components, and how they work together.
+sidebarTitle: Architecture
+---
+
+Understanding Chatwoot's architecture is crucial for successful deployment, scaling, and maintenance. This guide explains the core components and how they interact.
+
+## High-Level Architecture
+
+Chatwoot follows a modern, scalable web application architecture with clear separation of concerns:
+
+```mermaid
+graph TB
+    subgraph "Client Layer"
+        A[Web Dashboard]
+        B[Mobile Apps]
+        C[Website Widget]
+        D[API Clients]
+    end
+    
+    subgraph "Load Balancer"
+        E[Nginx/ALB]
+    end
+    
+    subgraph "Application Layer"
+        F[Rails Web Server]
+        G[Sidekiq Workers]
+        H[WebSocket Server]
+    end
+    
+    subgraph "Data Layer"
+        I[PostgreSQL]
+        J[Redis]
+        K[File Storage]
+    end
+    
+    subgraph "External Services"
+        L[SMTP Server]
+        M[Third-party APIs]
+        N[CDN]
+    end
+    
+    A --> E
+    B --> E
+    C --> E
+    D --> E
+    E --> F
+    E --> H
+    F --> G
+    F --> I
+    F --> J
+    G --> I
+    G --> J
+    F --> K
+    F --> L
+    F --> M
+    K --> N
+```
+
+## Core Components
+
+### 1. Web Application (Rails)
+
+The main application server built with Ruby on Rails handles:
+
+- **HTTP API endpoints** for all client interactions
+- **Authentication and authorization** for users and agents
+- **Business logic** for conversations, contacts, and workflows
+- **Real-time features** via ActionCable WebSockets
+- **File uploads and processing**
+
+**Key characteristics:**
+- Stateless design for horizontal scaling
+- RESTful API architecture
+- WebSocket support for real-time updates
+- Multi-tenant architecture support
+
+### 2. Background Workers (Sidekiq)
+
+Sidekiq handles asynchronous processing:
+
+- **Email notifications** and delivery
+- **Webhook processing** for integrations
+- **File processing** and optimization
+- **Report generation** and analytics
+- **Third-party API calls** (Facebook, WhatsApp, etc.)
+
+**Key characteristics:**
+- Redis-backed job queue
+- Retry mechanisms for failed jobs
+- Horizontal scaling support
+- Job prioritization and scheduling
+
+### 3. Database (PostgreSQL)
+
+PostgreSQL stores all application data:
+
+- **User accounts and authentication**
+- **Conversations and messages**
+- **Contact information and profiles**
+- **Configuration and settings**
+- **Analytics and reporting data**
+
+**Key characteristics:**
+- ACID compliance for data integrity
+- JSON support for flexible schemas
+- Full-text search capabilities
+- Horizontal scaling with read replicas
+
+### 4. Cache and Session Store (Redis)
+
+Redis provides high-performance caching and session management:
+
+- **Session storage** for user authentication
+- **Cache layer** for frequently accessed data
+- **Job queue** for background processing
+- **Real-time data** for WebSocket connections
+- **Rate limiting** and throttling
+
+**Key characteristics:**
+- In-memory performance
+- Persistence options available
+- Pub/Sub for real-time features
+- Clustering support for high availability
+
+### 5. File Storage
+
+Chatwoot supports multiple storage backends:
+
+- **Local filesystem** (development/small deployments)
+- **AWS S3** (recommended for production)
+- **Google Cloud Storage**
+- **Azure Blob Storage**
+- **MinIO** (self-hosted S3-compatible)
+
+**Stored content:**
+- User avatars and profile images
+- Message attachments and files
+- Email templates and assets
+- Exported reports and backups
+
+### 6. Reverse Proxy (Nginx)
+
+Nginx serves as the front-end proxy:
+
+- **SSL termination** and certificate management
+- **Static file serving** for assets
+- **Load balancing** across application instances
+- **Request routing** and filtering
+- **Compression** and caching headers
+
+## Data Flow
+
+### 1. Incoming Messages
+
+```mermaid
+sequenceDiagram
+    participant C as Customer
+    participant W as Widget/Channel
+    participant N as Nginx
+    participant R as Rails App
+    participant D as Database
+    participant Q as Redis Queue
+    participant S as Sidekiq
+    participant A as Agent Dashboard
+    
+    C->>W: Sends message
+    W->>N: HTTP/WebSocket request
+    N->>R: Forward request
+    R->>D: Store message
+    R->>Q: Queue notification job
+    R->>A: Real-time update (WebSocket)
+    Q->>S: Process notification
+    S->>D: Update delivery status
+```
+
+### 2. Agent Responses
+
+```mermaid
+sequenceDiagram
+    participant A as Agent
+    participant D as Dashboard
+    participant R as Rails App
+    participant DB as Database
+    participant Q as Redis Queue
+    participant S as Sidekiq
+    participant C as Customer
+    
+    A->>D: Types response
+    D->>R: Send message API
+    R->>DB: Store message
+    R->>Q: Queue delivery job
+    R->>D: Real-time update
+    Q->>S: Process delivery
+    S->>C: Deliver via channel
+    S->>DB: Update status
+```
+
+## Scaling Considerations
+
+### Horizontal Scaling
+
+Chatwoot is designed for horizontal scaling:
+
+**Web Servers:**
+- Stateless design allows multiple instances
+- Load balancer distributes traffic
+- Session data stored in Redis
+
+**Background Workers:**
+- Multiple Sidekiq processes can run
+- Jobs distributed across workers
+- Queue-based processing prevents overload
+
+**Database:**
+- Read replicas for query scaling
+- Connection pooling for efficiency
+- Partitioning for large datasets
+
+### Vertical Scaling
+
+For smaller deployments, vertical scaling is often sufficient:
+
+**CPU:** Background processing and real-time features
+**Memory:** Caching and session storage
+**Storage:** Database and file storage growth
+**Network:** WebSocket connections and API traffic
+
+## Security Architecture
+
+### Authentication Flow
+
+```mermaid
+graph LR
+    A[User Login] --> B[Rails Auth]
+    B --> C[JWT Token]
+    C --> D[API Requests]
+    D --> E[Token Validation]
+    E --> F[Authorized Access]
+```
+
+### Data Protection
+
+- **Encryption at rest** for sensitive data
+- **TLS encryption** for data in transit
+- **Input validation** and sanitization
+- **SQL injection** protection via ORM
+- **XSS protection** with content security policies
+
+### Access Control
+
+- **Role-based permissions** (Admin, Agent, etc.)
+- **Account-level isolation** in multi-tenant setup
+- **API rate limiting** to prevent abuse
+- **Audit logging** for compliance
+
+## Monitoring and Observability
+
+### Application Metrics
+
+- **Response times** and throughput
+- **Error rates** and exceptions
+- **Background job** processing times
+- **WebSocket connection** counts
+
+### Infrastructure Metrics
+
+- **CPU and memory** utilization
+- **Database performance** and connections
+- **Redis memory** usage and hit rates
+- **Storage usage** and I/O patterns
+
+### Logging Strategy
+
+- **Structured logging** with JSON format
+- **Centralized collection** (ELK, Fluentd)
+- **Log levels** for different environments
+- **Sensitive data** filtering
+
+## Deployment Patterns
+
+### Single Server
+
+Suitable for small teams and development:
+- All components on one server
+- SQLite or PostgreSQL database
+- Local file storage
+- Simple backup strategy
+
+### Multi-Server
+
+For production environments:
+- Separate database server
+- Dedicated Redis instance
+- Load-balanced web servers
+- Shared file storage (S3/NFS)
+
+### Containerized
+
+Using Docker and orchestration:
+- Container images for each component
+- Kubernetes or Docker Swarm
+- Service discovery and networking
+- Rolling updates and health checks
+
+### Cloud-Native
+
+Leveraging cloud services:
+- Managed databases (RDS, Cloud SQL)
+- Managed Redis (ElastiCache, MemoryStore)
+- Object storage (S3, GCS)
+- Load balancers and CDN
+
+## Performance Optimization
+
+### Database Optimization
+
+- **Indexing strategy** for common queries
+- **Connection pooling** to reduce overhead
+- **Query optimization** and monitoring
+- **Read replicas** for scaling reads
+
+### Caching Strategy
+
+- **Application-level caching** for expensive operations
+- **HTTP caching** for static assets
+- **Database query caching** with Redis
+- **CDN caching** for global distribution
+
+### Background Processing
+
+- **Job prioritization** for critical tasks
+- **Batch processing** for bulk operations
+- **Queue monitoring** and alerting
+- **Resource allocation** per job type
+
+---
+
+<Note>
+Understanding this architecture helps you make informed decisions about deployment, scaling, and maintenance of your Chatwoot instance.
+</Note>