sasa-maillist/web/README.md

Web Frontend for Mailing List Manager

This directory contains the web frontend for the Mailing List Manager - a clean, modern web interface for managing mailing lists and members.

Features

• 🔐 Token-based Authentication - Secure access using API tokens
• 📧 Mailing List Management - Create, edit, and delete mailing lists
• 👥 Member Management - Add, edit, and remove members
• 🔗 Subscription Management - Subscribe/unsubscribe members to/from lists
• 📱 Responsive Design - Works on desktop, tablet, and mobile devices
• 🎨 Clean UI - Modern, professional interface with intuitive navigation
• ⚡ Real-time Updates - Immediate feedback and data refresh

Architecture

Frontend Stack

• HTML5 - Semantic markup with accessibility features
• CSS3 - Modern styling with CSS Grid/Flexbox and custom properties
• Vanilla JavaScript - No frameworks, just clean ES6+ code
• Nginx - Static file serving with compression and caching

File Structure

web/
├── index.html           # Main HTML interface
├── static/
│   ├── css/
│   │   └── style.css    # Complete styling system
│   └── js/
│       ├── api.js       # API client for backend communication
│       ├── ui.js        # UI helpers and modal management
│       └── app.js       # Main application controller
├── Dockerfile           # Container configuration
├── nginx.conf           # Nginx server configuration
└── README.md           # This file

Usage

Development

1. Ensure the API is running on port 8000
2. Open index.html in a web browser
3. Enter your API token to authenticate
4. Start managing your mailing lists!

Production (Docker)

The web frontend is served using Nginx and included in the Docker Compose setup.

# Build and start all services
docker-compose up --build

# Access the web interface
open http://localhost:3000

Features Overview

Authentication

• Secure token-based authentication
• Token persistence in browser storage
• Automatic logout on authentication errors

Mailing Lists

• View all mailing lists in a clean table
• Create new lists with name, email, and description
• Edit existing list details
• Delete lists with confirmation
• View member count for each list
• Status indicators (Active/Inactive)

Members

• View all members with their details
• Add new members with name and email
• Edit member information
• Delete members with confirmation
• See which lists each member is subscribed to
• Status management

Subscriptions

• Visual subscription management interface
• Add members to mailing lists
• Remove members from lists
• See all subscriptions organized by list
• Quick unsubscribe functionality

User Experience

• Responsive Design - Works seamlessly on all device sizes
• Loading States - Visual feedback during API operations
• Error Handling - Clear error messages and graceful degradation
• Notifications - Success/error notifications with auto-dismiss
• Confirmation Dialogs - Prevent accidental deletions
• Keyboard Shortcuts - Enter key support in forms
• Accessibility - Semantic HTML and ARIA labels

API Integration

The frontend communicates with the FastAPI backend through a comprehensive API client:

• Authentication - Bearer token authentication
• Error Handling - Automatic error parsing and user-friendly messages
• Loading States - Integrated loading indicators
• Data Validation - Client-side form validation before API calls

Customization

Styling

The CSS uses CSS custom properties (variables) for easy theming:

:root {
    --primary-color: #2563eb;
    --success-color: #10b981;
    --danger-color: #ef4444;
    /* ... more variables */
}

Configuration

The API client automatically detects the backend URL based on the current hostname and can be configured for different environments.

Browser Support

• Modern browsers (Chrome 60+, Firefox 55+, Safari 12+, Edge 79+)
• Mobile browsers (iOS Safari 12+, Chrome Mobile 60+)
• Progressive enhancement for older browsers