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

Accessing the Interface

Via Docker (Recommended):

# Ensure all services are running
sudo docker-compose up -d

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

For Development: You can also open index.html directly in a browser, but the API must be running on port 8000.

Getting Started

1. Authenticate: Enter your API_TOKEN (from .env file) when prompted
2. Manage Lists: Click the "Lists" tab to view and manage mailing lists
3. Manage Members: Click the "Members" tab to add and edit member information
4. Manage Subscriptions: Click "Subscriptions" button on any member to toggle their list memberships

The interface saves your token in browser storage, so you won't need to re-enter it on subsequent visits.

Features Overview

Authentication

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

Subscription Management (New & Improved!)

Member-Centric Subscription Management

The subscription management has been completely redesigned for the best user experience:

How to Use:

1. Navigate to the Members tab
2. Find the member you want to manage
3. Click the "Subscriptions" button next to their name
4. A modal appears showing all available mailing lists with toggle switches

Visual Interface:

• Green toggle = Member is subscribed to this list
• Gray toggle = Member is not subscribed to this list
• Click anywhere on a list item to toggle subscription on/off

Batch Operations:

• Make multiple changes (subscribe to some lists, unsubscribe from others)
• The "Save Changes" button shows how many changes you've made (e.g., "Save 3 Changes")
• All changes are saved together when you click "Save Changes"
• Click "Cancel" to discard all changes

Benefits:

• ✅ Fast - Toggle multiple subscriptions at once
• ✅ Visual - See all subscriptions at a glance with color coding
• ✅ Intuitive - Works like modern mobile app switches
• ✅ Smart - Only saves actual changes, not unchanged items
• ✅ Clear - Shows exactly how many changes you're about to save

Alternative: Legacy Bulk Subscription

For power users who prefer the old approach:

1. Go to the Subscriptions tab
2. Select list and member from dropdowns
3. Click "Add Subscription"

This is still available but the member-centric approach is much more efficient for managing multiple subscriptions.

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

• Member-centric subscription management - Click on any member to manage their subscriptions
• Interactive toggle interface - Check/uncheck lists with visual toggles
• Batch changes - Make multiple subscription changes and save them all at once
• Real-time feedback - See subscription status instantly with visual indicators
• Subscription overview - View all subscriptions organized by list
• Quick add functionality - Legacy bulk subscription interface for power users

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