System Architecture Documentation

Overview
This document provides a detailed explanation of the AI-powered customer support
chatbot system architecture, including component interactions, data flow, and technical
decisions.

High-Level Architecture

┌────────────────────────────────────────────
│ Client Layer │
├────────────────────────────────────────────
│ Web Browser (HTML/CSS/JavaScript) │
│ - Chat Interface │
│ - Responsive Design │
│ - Real-time Updates │
└────────────────────────────────────────────
│
│ HTTP/HTTPS
│ REST API
▼
┌────────────────────────────────────────────
│ Application Layer │
├────────────────────────────────────────────
│ Flask Web Server │
│ ├── Static File Serving │
│ ├── API Endpoints │
│ ├── Request/Response Handling │
│ └── CORS Configuration │
└────────────────────────────────────────────
│
│ Function Calls
▼
┌────────────────────────────────────────────
│ Business Logic Layer │
├────────────────────────────────────────────
│ Chatbot Service │
│ ├── Message Processing │
│ ├── AI Response Generation │
│ ├── FAQ Matching │
│ ├── Escalation Logic │
│ └── Session Management │
 └────────────────────────────────────────────
│
│ ORM Queries
▼
┌────────────────────────────────────────────
│ Data Access Layer │
├────────────────────────────────────────────
│ SQLAlchemy ORM │
│ ├── Model Definitions │
│ ├── Database Abstraction │
│ ├── Query Optimization │
│ └── Transaction Management │
└────────────────────────────────────────────
│
│ SQL Queries
▼
┌────────────────────────────────────────────
│ Data Layer │
├────────────────────────────────────────────
│ SQLite Database │
│ ├── Conversations Table │
│ ├── Feedback Table │
│ ├── FAQ Table │
│ └── Users Table │
└────────────────────────────────────────────

Component Details

1. Client Layer (Frontend)

Technology Stack:
- HTML5 for structure
- CSS3 with modern features (Grid, Flexbox, Animations)
- Vanilla JavaScript (ES6+) for interactivity
- Font Awesome for icons

Key Components:

Chat Widget ( script.js )

class ChatbotApp {
// Manages entire chat experience
// - Session management
// - Message handling
// - API communication
 // - UI state management
}

Responsibilities:
- User interface rendering
- Real-time message display
- API communication
- Session management
- Responsive design adaptation

Design Patterns:
- Module Pattern: Encapsulated functionality in ChatbotApp class
- Observer Pattern: Event-driven UI updates
- Factory Pattern: Message creation and display

2. Application Layer (Flask Server)

Technology Stack:
- Flask 3.x web framework
- Flask-CORS for cross-origin requests
- Flask-SQLAlchemy for database ORM

Key Components:

Main Application ( src/main.py )

app = Flask(__name__)
# Configuration
# Blueprint registration
# Database initialization
# Static file serving

Route Blueprints

• User Routes ( src/routes/user.py ): User management (template)

• Chatbot Routes ( src/routes/chatbot.py ): Core chatbot functionality

Responsibilities:
- HTTP request/response handling
- Route management and URL mapping
- Static file serving
- CORS policy enforcement
- Error handling and logging
3. Business Logic Layer

Chatbot Service ( src/routes/chatbot.py )

Core Functions:

def get_ai_response_from_db(message):
# 1. Query FAQ database for keyword matches
# 2. Fallback to rule-based keyword matching
# 3. Return response and escalation flag

AI Logic Flow:

User Message
│
▼
FAQ Database Query
│
├─ Match Found ── Return FAQ Answer
│
└─ No Match ── Keyword Analysis
│
├─ Known Pattern ── Return Template Response
│
└─ Unknown ── Escalate to Human

Escalation Criteria:
- No FAQ match found
- No keyword pattern match
- User explicitly requests human agent
- Complex queries requiring human judgment

4. Data Access Layer

SQLAlchemy Models

Conversation Model ( src/models/conversation.py ):

class Conversation(db.Model):
id = db.Column(db.Integer, primary_key=True)
session_id = db.Column(db.String(100), nullable=False)
user_message = db.Column(db.Text)
ai_response = db.Column(db.Text)
escalated = db.Column(db.Boolean, default=False)
 timestamp = db.Column(db.DateTime, default=datetime.utcnow)
message_type = db.Column(db.String(20), default='chat')

Relationships:
- One-to-many: Session → Conversations
- One-to-many: Session → Feedback entries

5. Data Layer

Database Schema

-- Conversations table
CREATE TABLE conversations (
id INTEGER PRIMARY KEY AUTOINCREMENT,
session_id VARCHAR(100) NOT NULL,
user_message TEXT,
ai_response TEXT,
escalated BOOLEAN DEFAULT 0,
timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
message_type VARCHAR(20) DEFAULT 'chat'
);

-- Feedback table
CREATE TABLE feedback (
id INTEGER PRIMARY KEY AUTOINCREMENT,
session_id VARCHAR(100) NOT NULL,
rating INTEGER NOT NULL,
comment TEXT,
timestamp DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- FAQ table
CREATE TABLE faqs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
question TEXT NOT NULL,
answer TEXT NOT NULL,
category VARCHAR(50),
keywords TEXT,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
active BOOLEAN DEFAULT 1
);
Data Flow Diagrams

1. Chat Message Flow

User Types Message

│
▼
Frontend Validation
│
▼
POST /api/chat
│
▼
Backend Processing
│
├─ FAQ Query
├─ Keyword Matching
└─ Response Generation
│
▼
Database Storage
│
▼
JSON Response
│
▼
Frontend Display

2. Escalation Flow

AI Cannot Handle Query

│
▼
Escalation Flag Set
│
▼
POST /api/escalate
│
▼
Create Escalation Record
│
▼
Return Escalation Info
│
▼
Update UI State
3. Feedback Flow

User Clicks Rate Chat

│
▼
Modal Opens
│
▼
User Selects Rating
│
▼
POST /api/feedback
│
▼
Store in Database
│
▼
Confirmation Message

Security Architecture

Current Security Measures

1. Input Validation
2. Message length limits (500 characters)
3. Rating value validation (1-5 scale)

4. SQL injection prevention via ORM

5. CORS Configuration

6. Enabled for development

7. Configurable for production domains

8. Database Security

9. SQLAlchemy ORM prevents SQL injection

10. Parameterized queries
11. Transaction rollback on errors

Production Security Recommendations

# Authentication middleware
@app.before_request
 def authenticate_admin():
if request.endpoint.startswith('admin'):
# JWT token validation
pass

# Rate limiting
from flask_limiter import Limiter
limiter = Limiter(app, key_func=get_remote_address)

@limiter.limit("10 per minute")

@app.route('/api/chat', methods=['POST'])
def chat():
pass

Performance Considerations

Current Optimizations

1. Database Indexing
sql
CREATE INDEX idx_session_id ON conversations(session_id);
CREATE INDEX idx_timestamp ON conversations(timestamp);
CREATE INDEX idx_faq_active ON faqs(active);

2. Query Optimization

3. Pagination for conversation logs

4. Filtered queries for active FAQs

5. Efficient keyword matching

6. Frontend Performance

7. CSS animations for smooth UX

8. Debounced input validation
9. Efficient DOM manipulation

Scalability Improvements

1. Caching Layer ```python from flask_caching import Cache cache = Cache(app,

config={'CACHE_TYPE': 'redis'})

@cache.memoize(timeout=300)
def get_faq_responses():
 return FAQ.query.filter(FAQ.active == True).all()
```

1. Database Optimization
2. Connection pooling
3. Read replicas for analytics

4. Database partitioning by date

5. Load Balancing

6. Multiple Flask instances

7. Nginx reverse proxy
8. Session affinity for WebSocket upgrades

Monitoring and Observability

Logging Strategy

import logging
from flask.logging import default_handler

# Configure structured logging

logging.basicConfig(
level=logging.INFO,
format='%(asctime)s %(levelname)s %(name)s %(message)s'
)

# Log chat interactions

logger.info('Chat message processed', extra={
'session_id': session_id,
'message_length': len(user_message),
'escalated': needs_escalation,
'response_time': response_time
})

Metrics Collection

Key metrics to monitor:

- Response Time: API endpoint latency
- Escalation Rate: Percentage of conversations escalated
- User Satisfaction: Average feedback rating
- System Health: Database connection status, memory usage
Health Checks

@app.route('/api/health')
def health_check():
return {
'status': 'healthy',
'database': check_database_connection(),
'memory_usage': get_memory_usage(),
'uptime': get_uptime()
}

Deployment Architecture

Development Environment

Developer Machine
├── Python Virtual Environment
├── SQLite Database
├── Flask Development Server
└── Browser Testing

Production Environment

Load Balancer (Nginx)

├── Flask App Instance 1
├── Flask App Instance 2
└── Flask App Instance N
│
▼
Database Cluster
├── Primary Database (Write)
└── Read Replicas (Read)
│
▼
Monitoring Stack
├── Application Logs
├── Performance Metrics
└── Health Checks
Technology Decisions

Why Flask?

• Lightweight: Minimal overhead for API-focused application

• Flexible: Easy to extend and customize
• Python Ecosystem: Rich libraries for AI/ML integration
• Rapid Development: Quick prototyping and iteration

Why SQLite?

• Simplicity: Zero-configuration database

• Portability: Single file database
• Performance: Sufficient for moderate traffic
• Upgrade Path: Easy migration to PostgreSQL/MySQL

Why Vanilla JavaScript?

• No Dependencies: Reduced complexity and bundle size

• Performance: Direct DOM manipulation
• Compatibility: Works in all modern browsers
• Learning: Clear understanding of underlying concepts

Future Architecture Evolution

Phase 1: Enhanced AI

Current Keyword Matching

│
▼
OpenAI GPT Integration
│
▼
Custom NLP Models

Phase 2: Real-time Features

HTTP Polling
│
▼
WebSocket Integration
 │
▼
Real-time Human Agent Chat

Phase 3: Microservices

Monolithic Flask App

│
▼
Service Decomposition
├── Chat Service
├── AI Service
├── Analytics Service
└── User Service

This architecture provides a solid foundation for a customer support chatbot while
maintaining flexibility for future enhancements and scaling requirements.