Merge pull request #218 from sjefferson99/develop

v2026.1.0 - UI release

Author: sjefferson99

.env

@@ -6,4 +6,21 @@ MYSQL_PASSWORD=your_user_password_here
 
 # Application Configuration
 FLASK_ENV=development
-FLASK_DEBUG=1
+FLASK_DEBUG=1
+
+# Redis Configuration
+REDIS_URL=redis://redis:6379/0
+
+# CORS Configuration
+# Comma-separated list of origins allowed to connect via HTTP, HTTPS, and WebSocket
+# For development: include both localhost and 127.0.0.1 since they're different CORS origins
+# If you access the app via another hostname or IP (e.g., http://192.168.1.100), add that origin here as well.
+# For production: https://yourdomain.com,https://www.yourdomain.com
+CORS_ALLOWED_ORIGINS=http://localhost,http://127.0.0.1
+
+# WebSocket Testing Configuration
+# Set to true to test WebSocket disconnection scenarios (header shows "WebSocket Disconnected")
+# WARNING: This must NEVER be enabled (true) in production deployments
+# Only use for local/testing purposes to verify client handling of WebSocket failures
+# Default: false
+REJECT_SOCKETIO_CONNECTIONS=false

.env.example

@@ -0,0 +1,26 @@
+# Database Configuration
+MYSQL_ROOT_PASSWORD=your_root_password_here
+MYSQL_DATABASE=aft_db
+MYSQL_USER=aft_user
+MYSQL_PASSWORD=your_user_password_here
+
+# Application Configuration
+FLASK_ENV=development
+FLASK_DEBUG=1
+
+# Redis Configuration
+REDIS_URL=redis://redis:6379/0
+
+# CORS Configuration
+# Comma-separated list of origins allowed to connect via HTTP, HTTPS, and WebSocket
+# For development: include both localhost and 127.0.0.1 since they're different CORS origins
+# If you access the app via another hostname or IP (e.g., http://192.168.1.100), add that origin here as well.
+# For production: https://yourdomain.com,https://www.yourdomain.com
+CORS_ALLOWED_ORIGINS=http://localhost,http://127.0.0.1
+
+# WebSocket Testing Configuration
+# Set to true to test WebSocket disconnection scenarios (header shows "WebSocket Disconnected")
+# WARNING: This must NEVER be enabled (true) in production deployments
+# Only use for local/testing purposes to verify client handling of WebSocket failures
+# Default: false
+REJECT_SOCKETIO_CONNECTIONS=false

.gitignore

@@ -1,6 +1,7 @@
 .vscode
 data
 backups
+.env
 
 # Python virtual environments
 venv/

CONTRIBUTING.md

@@ -9,13 +9,14 @@ Before submitting any code contribution, **verify ALL items** are complete:
 - [ ] **Tests Created** - All new features and bug fixes MUST include tests (see [Testing Requirements](#testing-requirements))
 - [ ] **API-Only Tests** - Tests use ONLY API endpoints, never direct database/filesystem access (see [TESTING.md](./TESTING.md))
 - [ ] **Code Standards** - Code follows all style guidelines in [Coding Standards](#coding-standards)
+- [ ] **Frontend Error Handling** - All API calls follow error handling patterns (see [FRONTEND_ERROR_HANDLING.md](./FRONTEND_ERROR_HANDLING.md))
 - [ ] **Accessibility** - UI changes include ARIA attributes, keyboard navigation, screen reader support (see [Accessibility Requirements](#accessibility-requirements))
 - [ ] **Security** - Input validation, length limits, no error leaking (see [Security Guidelines](#security-guidelines))
 - [ ] **Database Changes** - Migration created, schema validation updated (see [Database Changes](#database-changes))
 - [ ] **Documentation** - README/docs updated if behavior changed
 - [ ] **All Tests Pass** - Run `pytest -v` and verify all tests pass
 
-**AI Contributors:** Read this entire document including all linked files (TESTING.md, ACCESSIBILITY.md, MIGRATION_GUIDE.md) before implementing ANY feature.
+**AI Contributors:** Read this entire document including all linked files (TESTING.md, ACCESSIBILITY.md, MIGRATION_GUIDE.md, FRONTEND_ERROR_HANDLING.md) before implementing ANY feature.
 
 ## Table of Contents
 
@@ -79,7 +80,7 @@ I had copilot write all of this primarily so I can ensure it always does all the
 5. **Verify Setup**
 
    - Application: http://localhost:80
-   - API: http://localhost:5000/api/health
+   - API: http://localhost/api/health
 
 ## Development Workflow
 
@@ -469,6 +470,29 @@ All UI changes must meet accessibility standards. See [ACCESSIBILITY.md](./ACCES
 3. Test with a screen reader
 4. Run automated tools (axe DevTools, Lighthouse)
 
+## Frontend Error Handling
+
+All frontend API interactions must follow error handling best practices to ensure a consistent user experience when the database or API is unavailable.
+
+See [FRONTEND_ERROR_HANDLING.md](./FRONTEND_ERROR_HANDLING.md) for comprehensive guidelines on:
+
+- **Database Connection Monitoring**: Continuous polling and status tracking
+- **API Call Patterns**: 5-second timeouts with AbortController
+- **Visual Feedback**: Loading states, toast notifications, loading overlays
+- **State Preservation**: Keep modals open on failure, rollback UI changes
+- **Error Notifications**: Non-blocking toasts instead of blocking alerts
+- **Testing Guidelines**: Manual and automated testing requirements
+
+### Quick Reference
+
+All API calls must:
+1. Use AbortController with 5-second timeout
+2. Show loading state (with 500ms delay to avoid flashing)
+3. Display non-blocking toast on error (never use `alert()`)
+4. Preserve user work on failure (keep modals open)
+5. Rollback UI changes for optimistic updates
+6. Check database connection before opening modals
+
 ## Security Guidelines
 
 All code must follow security best practices. See [server/SECURITY.md](./server/SECURITY.md) for comprehensive security guidelines.