chaulmark/deafgain-website
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
deafgain-website/DEVELOPMENT_DOCUMENTATION.txt

492 lines
18 KiB
Text
Raw Blame History

# DeafGain Website - Complete Development Documentation
## Technical Stack Overview & Recent Enhancements
================================================================================
PROJECT OVERVIEW
================================================================================
DeafGain LLC Website serves as a comprehensive digital platform dedicated to
empowering the Deaf community through innovative communication solutions,
professional training resources, and accessibility services. The website
focuses on providing ADA-compliant content with full accessibility features
including WebVTT subtitles, transcriptions, and universal design principles.
Live Production URL: https://deafgain.org/
Development Server: http://localhost:5173
================================================================================
TECHNOLOGY STACK - COMPREHENSIVE BREAKDOWN
================================================================================
FRONTEND TECHNOLOGIES
---------------------
- React 19.0.0 - Core UI framework with latest features
- TypeScript 5.7.2 - Type safety and enhanced development experience
- React Router 7.6.1 - Client-side routing with latest security fixes
- Tailwind CSS 3.4.16 - Utility-first CSS framework for rapid styling
- Framer Motion 11.13.5 - Advanced animations and micro-interactions
- React Simple Maps 4.0.0-beta.6 - Geographic visualization components
- React Icons 5.4.0 - Comprehensive icon library
- React Intersection Observer 9.13.1 - Scroll detection and lazy loading
BACKEND TECHNOLOGIES
--------------------
- Express.js 4.21.2 - Web application framework for Node.js
- Node.js (Latest LTS) - JavaScript runtime environment
- Nodemailer 6.9.9 - Email service integration
- Upstash Redis 1.28.4 - Cloud Redis for caching and rate limiting
- TypeScript 5.7.2 - Backend type safety
- dotenv 16.4.7 - Environment variable management
DEVELOPMENT & BUILD TOOLS
-------------------------
- Vite 6.3.5 - Lightning-fast build tool and dev server
- pnpm 9.14.2 - Efficient package manager
- ESLint 9.15.0 - Code quality and consistency enforcement
- PostCSS 8.4.49 - CSS processing and optimization
- Autoprefixer 10.4.20 - CSS vendor prefix automation
- Concurrently 9.1.2 - Parallel process management
- tsx 4.19.4 - TypeScript execution for development
DEPLOYMENT & INFRASTRUCTURE
----------------------------
- Docker & Docker Compose - Containerization and orchestration
- Nginx - Reverse proxy and static file serving
- Redis - Session management and caching
- Gmail SMTP - Email service integration
- Caddy Reverse Proxy - Production load balancing
================================================================================
ARCHITECTURE OVERVIEW
================================================================================
FRONTEND ARCHITECTURE
---------------------
The application follows a modern React architecture with:
1. Component Structure:
- Layout components (Navbar, Footer) for consistent structure
- Page components for route-specific content
- Shared components for reusability
- Context providers for global state management
2. State Management:
- React Context for global application state
- Local component state for UI-specific data
- Notification context for toast messaging system
3. Routing System:
- React Router v7 for client-side navigation
- Protected routes and dynamic routing
- Direct video linking with URL parameters
BACKEND ARCHITECTURE
--------------------
Express.js RESTful API with:
1. API Structure:
- RESTful endpoints for contact and subscription
- Rate-limited routes for security
- Error handling and input validation
2. Services:
- Email service with professional templates
- Redis-backed caching and session management
- Rate limiting middleware
SECURITY IMPLEMENTATION
-----------------------
- Input validation and sanitization
- Rate limiting on API endpoints (Redis-backed)
- CORS policy configuration
- Environment variable protection
- Secure email handling with app passwords
================================================================================
RECENT ENHANCEMENTS - VIDEO CARD INTERFACE IMPROVEMENTS
================================================================================
OVERVIEW OF MODIFICATIONS
-------------------------
Recent updates to the Resources page video library interface focus on enhanced
user experience, modern visual design, and improved accessibility. These changes
maintain full functionality while significantly upgrading the visual appeal.
DETAILED CHANGES IMPLEMENTED
----------------------------
1. ENHANCED CARD DESIGN
- Border Radius: Upgraded from 'rounded-lg' to 'rounded-xl' for modern aesthetics
- Shadow System: Enhanced from 'shadow-md' to 'shadow-lg' with 'hover:shadow-2xl'
- Subtle Borders: Added 'border border-gray-100' for better card definition
- Hover Effects: Implemented lift animation 'hover:-translate-y-2' for interactivity
2. ADVANCED ANIMATION SYSTEM
- Staggered Entrance: Cards animate in sequentially with index-based delays
- Smooth Transitions: Enhanced image scaling from 'scale-105' to 'scale-110'
- Micro-interactions: Added Framer Motion 'whileHover' and 'whileTap' effects
- Duration Control: Optimized animation timing for professional feel
3. IMPROVED VISUAL HIERARCHY
- Always-Visible Play Icon: Added semi-transparent play button in top-right
- Gradient Overlays: Implemented 'bg-gradient-to-t from-black/70' for readability
- Typography Enhancement: Larger titles with improved line-height and spacing
- Color Transitions: Added hover color changes for better user feedback
4. ENHANCED BUTTON INTERFACE
- Primary Action Styling: "Watch Video" button uses gradient background
- Secondary Button Design: "Share" and "Transcript" use backdrop blur effects
- Consistent Spacing: Improved button layouts and grouping
- Professional Appearance: Added borders and enhanced shadow effects
5. CONTENT LAYOUT IMPROVEMENTS
- Increased Grid Spacing: Changed from 'gap-6' to 'gap-8' for better breathing room
- Enhanced Padding: More generous content padding throughout cards
- Action Bar Addition: Bottom section with professional training indicators
- Visual Elements: Added decorative dot patterns for polish
TECHNICAL IMPLEMENTATION DETAILS
--------------------------------
File Modified: src/pages/Resources.tsx
Lines Changed: Approximately 150-250 (video card rendering section)
Key Code Changes:
- Added staggered animation with index-based delays
- Implemented gradient overlays for better text contrast
- Enhanced button styling with Framer Motion animations
- Added professional indicators and visual elements
- Improved responsive design considerations
Performance Considerations:
- Animations are GPU-accelerated using CSS transforms
- Lazy loading maintained for video thumbnails
- No impact on existing functionality or loading times
- Accessibility features preserved and enhanced
================================================================================
DEVELOPMENT SETUP INSTRUCTIONS
================================================================================
PREREQUISITES
-------------
- Node.js LTS version (18.x or higher)
- pnpm 9.14.2 (package manager)
- Docker & Docker Compose (for containerized development)
- Git for version control
LOCAL DEVELOPMENT SETUP
-----------------------
1. Clone Repository:
git clone [repository-url]
cd deafgain-website
2. Install Dependencies:
pnpm install
3. Environment Configuration:
cp .env.example .env
# Configure the following variables:
- GMAIL_USER=your-email@gmail.com
- GMAIL_PASS=your-app-password
- REDIS_URL=your-redis-url
- REDIS_TOKEN=your-redis-token
4. Start Development Servers:
pnpm dev
# This starts both frontend (port 5173) and backend (port 804)
5. Access Application:
Frontend: http://localhost:5173
API: http://localhost:804
DOCKER DEVELOPMENT
------------------
Alternative development setup using Docker:
1. Development Environment:
docker-compose -f docker-compose.dev.yml up
2. Production Build:
docker-compose up --build
AVAILABLE SCRIPTS
-----------------
- pnpm dev - Start development servers (frontend + backend)
- pnpm build - Build for production
- pnpm preview - Preview production build locally
- pnpm lint - Run ESLint code quality checks
================================================================================
PRODUCTION DEPLOYMENT
================================================================================
DEPLOYMENT ARCHITECTURE
-----------------------
Production deployment utilizes a multi-container Docker setup:
1. Web Container (Nginx):
- Serves static frontend files
- Handles routing for single-page application
- Configured reverse proxy for API endpoints
2. API Container (Node.js):
- Express.js server handling API requests
- Email service integration
- Rate limiting and security middleware
3. Redis Container:
- Caching layer for improved performance
- Session management
- Rate limiting storage
PRODUCTION CONFIGURATION
------------------------
- Container Names: deafgain-website-web-1, deafgain-website-api-1
- Network: Integrated with Caddy reverse proxy (caddy_network)
- Ports: Web (804), API (3000), Redis (internal)
- Volumes: Video content mounted from host system
ENVIRONMENT VARIABLES (Production)
----------------------------------
Required environment variables for production:
- GMAIL_USER: Email service authentication
- GMAIL_PASS: Gmail app password
- REDIS_URL: Production Redis connection string
- REDIS_TOKEN: Redis authentication token
- NODE_ENV: Set to 'production'
================================================================================
KEY FEATURES & FUNCTIONALITY
================================================================================
VIDEO RESOURCE LIBRARY
-----------------------
- 6 Professional development videos with full accessibility
- WebVTT subtitle support for hearing accessibility
- Complete transcriptions with scene descriptions
- Modal video player with native HTML5 controls
- Share functionality with direct video linking
- Responsive grid layout (1/2/3 columns based on screen size)
EMAIL SUBSCRIPTION SYSTEM
--------------------------
- Professional subscription form with validation
- Rate-limited API endpoints for security
- Gmail SMTP integration with branded templates
- Redis-backed subscriber management
- Success/error notification system
ACCESSIBILITY FEATURES
----------------------
- WCAG 2.1 Level AA compliance
- Screen reader compatibility
- Keyboard navigation support
- High contrast color ratios
- Alternative text for all images
- Semantic HTML structure
INTERACTIVE COMPONENTS
----------------------
- Custom video player with accessibility controls
- Snow peaks animation effect
- Contact form with real-time validation
- Toast notification system
- Responsive navigation with mobile support
================================================================================
FILE STRUCTURE & ORGANIZATION
================================================================================
ROOT LEVEL
----------
├── src/ # Source code directory
├── public/ # Static assets
├── cline_docs/ # Development documentation
├── docker-compose.yml # Production container config
├── docker-compose.dev.yml # Development container config
├── package.json # Dependencies and scripts
├── tailwind.config.js # Tailwind CSS configuration
├── tsconfig.json # TypeScript configuration
└── vite.config.ts # Vite build configuration
SOURCE CODE STRUCTURE
---------------------
src/
├── api/ # Backend API routes
│ ├── contact.ts # Contact form handler
│ └── subscribe.ts # Email subscription handler
├── components/ # React components
│ ├── Layout/ # Layout components
│ │ ├── Navbar.tsx # Navigation component
│ │ ├── Footer.tsx # Footer component
│ │ └── Layout.tsx # Main layout wrapper
│ ├── shared/ # Reusable components
│ │ └── Toast.tsx # Notification component
│ ├── VideoPlayer.tsx # Custom video player
│ └── SnowPeaks.tsx # Animation component
├── context/ # React Context providers
│ ├── notification-context.ts
│ └── NotificationProvider.tsx
├── lib/ # Utility functions
│ ├── email.ts # Email service utilities
│ └── rate-limit.ts # Rate limiting logic
├── pages/ # Route components
│ ├── Home.tsx # Landing page
│ ├── About.tsx # About page
│ ├── Services.tsx # Services showcase
│ ├── Resources.tsx # Video library (recently enhanced)
│ └── Contact.tsx # Contact form
└── main.tsx # Application entry point
PUBLIC ASSETS STRUCTURE
-----------------------
public/
├── images/
│ ├── thumbnails/ # Video thumbnail images
│ ├── eliza.jpg # Profile images
│ └── scene.jpg # Background images
├── subtitles/ # WebVTT subtitle files
├── transcriptions/ # Full text transcriptions
└── videos/ # Video content files
================================================================================
PERFORMANCE OPTIMIZATION
================================================================================
FRONTEND OPTIMIZATIONS
----------------------
- Tree shaking for minimal bundle size
- Code splitting for faster initial loads
- Image optimization and lazy loading
- CSS purging for reduced stylesheet size
- Modern JavaScript features for better performance
BACKEND OPTIMIZATIONS
---------------------
- Redis caching for frequently accessed data
- Rate limiting to prevent abuse
- Optimized database queries
- Gzip compression for API responses
- Static file serving through Nginx
DEPLOYMENT OPTIMIZATIONS
------------------------
- Multi-stage Docker builds for smaller images
- Nginx for efficient static file serving
- CDN-ready asset organization
- Production build optimization
- Container resource allocation
================================================================================
SECURITY CONSIDERATIONS
================================================================================
API SECURITY
------------
- Rate limiting on all public endpoints
- Input validation and sanitization
- CORS policy configuration
- Environment variable protection
- Secure email handling
DATA PROTECTION
---------------
- No sensitive data stored in client-side code
- Secure credential management
- Redis session security
- Email data encryption in transit
DEPLOYMENT SECURITY
-------------------
- Container isolation
- Secure environment variable handling
- Network segmentation
- SSL/TLS termination at proxy level
================================================================================
MAINTENANCE & MONITORING
================================================================================
REGULAR MAINTENANCE TASKS
--------------------------
1. Dependency Updates:
- Monthly security patch reviews
- Quarterly major version updates
- Browser compatibility testing
2. Performance Monitoring:
- Load time analysis
- Core Web Vitals tracking
- Error rate monitoring
3. Content Management:
- Video content updates
- Subtitle accuracy verification
- Transcription quality checks
TROUBLESHOOTING GUIDE
---------------------
1. Development Issues:
- Clear node_modules and reinstall dependencies
- Check environment variable configuration
- Verify port availability (5173, 804)
2. Production Issues:
- Check container logs: docker logs [container-name]
- Verify environment variables in production
- Monitor Redis connection health
3. Email Service Issues:
- Verify Gmail app password configuration
- Check SMTP connection settings
- Review rate limiting logs
================================================================================
FUTURE DEVELOPMENT ROADMAP
================================================================================
PLANNED ENHANCEMENTS
--------------------
1. Additional Video Categories:
- Communication training modules
- Leadership development series
- Technical skill workshops
2. User Experience Improvements:
- Video progress tracking
- User preference settings
- Advanced search functionality
3. Administrative Features:
- Content management system
- Analytics dashboard
- User engagement metrics
TECHNICAL IMPROVEMENTS
----------------------
1. Performance Enhancements:
- Service worker implementation
- Advanced caching strategies
- Progressive web app features
2. Accessibility Enhancements:
- Enhanced screen reader support
- Voice navigation capabilities
- Multi-language subtitle support
================================================================================
CONTACT & SUPPORT
================================================================================
For technical questions or development support:
- Production URL: https://deafgain.org/
- Development Environment: http://localhost:5173
- Documentation Location: cline_docs/ directory
- Recent Changes: See Git commit history for detailed change log
This documentation should be updated with each major release or significant
feature addition to maintain accuracy and usefulness for the development team.
Last Updated: May 30, 2025
Version: 1.0 (Post Video Card Enhancement)
Reference in a new issue View git blame Copy permalink