Welcome Window Customer Support

The Welcome Window is a Flask-based customer service application designed to make live support feel personal and engaging. It provides a professional interface where customers can request access, wait for approval, and connect via real-time chat or video while playing interactive games during wait times.

The project addresses a common problem in customer service: the awkward waiting period. Instead of staring at a loading spinner or empty chat box, visitors can play Word Search, Sudoku, or Trivia while waiting for responses. The appointment-based access model ensures the host maintains control over when and how they engage with customers.

• Real-time availability status system (Available, Busy, Away)
• Visitor approval workflow with name and email collection
• Live bidirectional chat with Socket.IO
• Interactive games: Word Search (10 themes), Sudoku (3 difficulty levels), Trivia (Open Trivia Database API)
• Optional Jitsi Meet video chat integration
• Admin dashboard with visitor monitoring and queue management
• Guest book for asynchronous messages
• Visit analytics and duration tracking

The application is deployed in production at welcome.todiane.com and demonstrates proficiency in real-time web applications, WebSocket communication, session management, and full-stack development.

Architecture & Stack:

The application uses Flask 3.1.0 with Flask-SocketIO 5.4.1 running in eventlet async mode for reliable real-time communication. After initial development with threading mode, I discovered limitations in socket-based notifications and migrated to eventlet for proper bidirectional WebSocket support.

Backend Technologies:

• Flask 3.1.0: Web framework and routing
• Flask-SocketIO 5.4.1: Real-time bidirectional communication
• Eventlet: Async mode for WebSocket reliability
• SQLite with WAL mode: Database with concurrent access support
• Python 3.8+: Core language

Frontend Technologies:

• Tailwind CSS: Utility-first styling with CDN delivery
• Alpine.js: Reactive components without build tools
• Socket.IO client: WebSocket client library
• Jitsi Meet: Embedded video conferencing

Database Schema:

The SQLite database uses five core tables:

• availability - Current status and custom messages
• messages - Guest book entries with read tracking
• visits - Session logs with duration calculation
• pending_visitors - Access requests with approval workflow
• chat_messages - Persistent chat history with sender attribution

Game Implementations:

Word Search: Python-based grid generator with 10 themed word lists (Animals, Food, Travel, Tech, Nature, Music, Sports, Movies, Space, Christmas). Client-side JavaScript handles cell selection, word validation, and progress tracking.

Sudoku: Server-side puzzle generation with backtracking algorithm. Three difficulty levels (easy: 30 cells removed, medium: 40, hard: 50). Client validates solutions and highlights errors in real-time.

Trivia: Integration with Open Trivia Database API. Supports category filtering, difficulty selection, and configurable question count. Client-side timer with point scoring based on response speed.

Real-time Communication:

Socket.IO events handle all real-time updates:

• Admin joins dedicated "admin" room via join_admin event
• Visitor connections tracked in active_connections dictionary
• Chat messages broadcast to all connected sockets via send_message event
• Approval notifications sent via approval_granted/approval_rejected
• Forced disconnections handled via force_disconnect event
• Polling fallbacks implemented for reliability (2-3 second intervals)

Session Management:

Visitor sessions use server-side Flask sessions with 16-byte random identifiers. Admin authentication uses session-based login with configurable credentials via environment variables. **Deployment Configuration:** Production deployment on Ubuntu VPS:

• Caddy: Reverse proxy with automatic SSL via Let's Encrypt
• systemd: Process management with auto-restart on failure
• SQLite WAL mode: Concurrent read access for multiple connections
• Environment variables: Secret key, admin credentials, feature flags

Production Deployment: The Welcome Window is live and fully functional for customer service operations. The application successfully handles:

• Real-time visitor approval workflow
• Simultaneous chat connections with message persistence
• Game playability without performance degradation
• Video chat integration via Jitsi Meet
• Admin dashboard with live visitor monitoring

Technical Achievements:

• Eventlet Migration: Resolved critical real-time messaging issues by switching from threading to eventlet async mode, enabling proper socket communication for admin notifications
• Chat Privacy: Implemented visitor-specific message filtering to prevent cross-contamination between different visitor conversations
• Polling Fallbacks: Added 2-3 second polling intervals as backup to socket events, ensuring message delivery even during connection instability
• Database Optimization: SQLite with WAL mode proved sufficient for concurrent access without requiring PostgreSQL migration
• Zero-Dependency Frontend: Achieved reactive UI with Alpine.js and Tailwind CSS via CDN, eliminating build tools

Code Quality:

• Manual deployment via scp upload to VPS (local development, remote deployment)
• Comprehensive admin/visitor interface separation
• Proper error handling and fallback mechanisms
• Session-based security with environment variable configuration

User Experience:

• Instant status updates without page refresh
• Clear visual feedback for all actions (approval pending, message sent, game completion)
• Smooth transitions between connection modes (chat vs video)
• Intuitive admin dashboard with one-click actions
• Mobile-responsive design across all pages

Project Outcomes:

This project demonstrates:

• Full-stack Flask development with real-time features
• WebSocket implementation and debugging
• Database design and session management
• External API integration (Open Trivia Database)
• Production deployment with SSL and process management
• Iterative problem-solving (threading → eventlet migration)

The Welcome Window serves as a complete example of building a professional customer service portal from scratch, with particular emphasis on real-time communication, user experience, and production-ready deployment practices.