Skip to main content
Version: 1.0.0

Structure

Author: Domenico Cerone Creation Date: 13/10/2025
Last Reviewer: Domenico Cerone

This document describes the Frame Validation project structure, its main components, and system architecture within the ARShades Studio ecosystem.

Project Structure​

frameValidation/
├── modal/                               # Modal components and related sub-modules
│   ├── tagsBadgesLine/                  # Specific modals for managing tags, badges and lines
│   │   ├── AddNewBadge.js
│   │   ├── AddNewLine.js
│   │   ├── AddNewTag.js
│   │   ├── CreateNewBadge.js
│   │   └── CreateNewTag.js
│   │
│   ├── DeclineModal.js
│   ├── EditProductsModal.js
│   ├── ImagePositioningModal.js
│   ├── NoteViewerModal.js
│   ├── NotificationsDropdown.js
│   ├── Publish3DAssetsModal.js
│   ├── TypeOfModellingModal.js
│   ├── VariantAssignedToModal.js
│   └── VariantsAssignedToModal.js
│
├── pages/                               # Main application pages
│   ├── DownloadLog.js
│   ├── Home.js
│   ├── Log.js
│   ├── Notifications.js
│   ├── Products.js
│   ├── ReportBrand.js
│   ├── VariantDetails.js
│   └── Variants.js
│
└── services/                            # Services and API/backend communication logic
    ├── CatalogOrderUtils.js             # Utilities for order and catalog management
    └── Utils/                           # Service functions and helpers
        ├── index.js
        ├── LogVariantService.js
        ├── NotificationService.js
        ├── RolePermissions.js
        └── StatusAccess.js

Quick Navigation:

Core Components​

Tag, Badge & Line Management (modal/tagsBadgesLine/)​

AddNewBadge.js​

Purpose: Modal component for adding existing featured badges to products with radio button selection interface and duplicate prevention validation.

Key Features: Fetches available badges from "Tags" collection with group "Featured", radio button grid layout with responsive styling, duplicate badge validation with warning notifications, real-time product data fetching for current state, automatic modal state reset on close, and comprehensive error handling with success notifications.

Implementation: React functional component with useState for selectedBadgeId and availableBadges, useEffect for data fetching and state reset, Firestore integration with collection queries and document updates, MediumModal wrapper with 700px width, Radio.Group with grid layout styling, and comprehensive error handling with notification system integration.

AddNewLine.js​

Purpose: Full-screen modal component for adding line-specific tags to products with group filtering and comprehensive tag selection interface.

Key Features: Filters tags exclusively for "Line" group, full-screen modal layout for enhanced visibility, Select dropdown for group selection with Radio button grid for tag selection, updates product's list_line_tags array, automatic group filtering with hardcoded "Line" restriction, and comprehensive duplicate prevention with validation.

Implementation: React functional component with useState for tag selection and group management, useEffect for group fetching and tag loading, Firestore integration with where queries for group filtering, FullScreenModal wrapper with custom styling, Select and Radio.Group components with responsive grid layout, and comprehensive error handling with notification integration.

AddNewTag.js​

Purpose: Medium-sized modal component for adding general category tags to products with group-based filtering and comprehensive tag management.

Key Features: Excludes "Line" and "Featured" groups for general tag selection, medium modal layout with 700px width, Select dropdown with Radio grid for tag selection, updates product's list_tags array, dynamic group loading with filtering logic, and comprehensive validation with duplicate prevention.

Implementation: React functional component with useState for tag and group selection, useEffect for group fetching and tag loading, Firestore integration with filtered group queries, MediumModal wrapper with custom styling, Select and Radio.Group components with responsive grid layout, and comprehensive error handling with notification system.

CreateNewBadge.js​

Purpose: Modal component for creating new featured badges with comprehensive customization options including colors, icons, and automatic product assignment.

Key Features: Complete badge creation with name, short name, background color (#000000 default), text color (#ffffff default), icon upload with base64 conversion, automatic group assignment to "Featured", immediate product assignment after creation, and comprehensive form validation.

Implementation: React functional component with useState for newBadgeData management, Upload component with beforeUpload validation, Firestore integration with addDoc for badge creation and updateDoc for product assignment, MediumModal wrapper with form controls, comprehensive form validation with required field checking, and automatic form reset functionality.

CreateNewTag.js​

Purpose: Modal component for creating new tags with dynamic group selection and automatic product assignment functionality.

Key Features: Dynamic group loading from existing Firestore tags, Select component with search and filter capabilities, new tag creation with group and name specification, automatic product assignment to list_tags array, comprehensive form validation with required field checking, and loading states for group fetching.

Implementation: React functional component with useState for tag data and group management, useEffect for existing group fetching, Firestore integration with getDocs for group loading and addDoc for tag creation, MediumModal wrapper with form controls, Select component with search functionality, and comprehensive error handling with validation.

Other Modal Components (modal/)​

DeclineModal.js​

Purpose: Comprehensive modal component for variant decline workflow with detailed issue reporting, severity classification, image uploads, and reference image management for quality assurance documentation.

Key Features: Multi-step form validation with issue title, decline reasons (checkbox selection with custom option), severity levels (Minor/Major/Critical) with color-coded badges, dual image upload system (screenshots and reference images), automatic image compression with quality optimization, Firebase Storage integration with organized path structure, comprehensive form validation with required field checking, and automatic modal state management with form reset functionality.

Implementation: React functional component with useState for form data and compression states, custom image compression function with canvas manipulation, Firebase Storage integration with uploadBytes and getDownloadURL, Form validation with Ant Design Form.Item rules, dual Upload components with customRequest handlers, comprehensive error handling with notification system integration, and automatic file naming with timestamp and UUID for asset organization.

EditProductsModal.js​

Purpose: Multi-language product description editor providing tabbed interface for managing product descriptions across different locales with direct Firestore integration for real-time updates.

Key Features: Multi-language support (EN, IT, DE, ES, FR) with tabbed interface, real-time Firestore document updates, auto-resizing TextArea components for optimal content editing, form validation with Ant Design Form integration, immediate save functionality with success/error notifications, and responsive design with consistent styling across language tabs.

Implementation: React functional component with useEffect for initial data loading, Firestore integration with updateDoc for real-time updates, Ant Design Tabs component with TabPane for language switching, Form component with layout="vertical" for optimal form structure, comprehensive error handling with try-catch blocks, and automatic form field population with setFieldsValue for seamless data loading.

ImagePositioningModal.js​

Purpose: Advanced image positioning and cropping modal with real-time canvas preview, drag-and-drop positioning, scale adjustment, and circular crop output for profile images and asset management.

Key Features: Real-time canvas preview with circular clipping mask, interactive drag-and-drop positioning system, scale adjustment with slider control (50%-300%), live position and scale feedback display, high-quality output generation (400px resolution), automatic image processing with base64 conversion, reset functionality for position and scale, and comprehensive error handling with fallback mechanisms.

Implementation: React functional component with useState for position, scale, and drag states, useEffect for image URL management and canvas drawing, custom canvas manipulation with getContext and drawImage, mouse event handlers for drag functionality, Promise-based image generation with toBlob conversion, automatic cleanup with URL.revokeObjectURL, and comprehensive error handling with user feedback notifications.

NoteViewerModal.js​

Purpose: Comprehensive validation notes viewer with read status management, image galleries, severity indicators, and user profile integration for complete decline note visualization and tracking.

Key Features: Multi-note display with chronological ordering, read status tracking with automatic updates, user profile resolution with full name display, severity level visualization with color-coded badges, image gallery with zoom functionality and download capabilities, reference image management with separate display section, comprehensive note metadata display (date, assignee, status), and automatic modal content generation with scrollable interface.

Implementation: React functional component with useState for read status management, useEffect for note status checking, Firestore integration with getDoc and updateDoc for status updates, Modal.info for dynamic content display, comprehensive image handling with click-to-zoom functionality, user profile mapping with case-insensitive email matching, automatic status updates with readBy tracking, and comprehensive error handling with fallback display options.

NotificationsDropdown.js​

Purpose: Advanced notification management system with grouped notifications, real-time updates, Redux integration, and comprehensive notification lifecycle management for the Frame Validation dashboard.

Key Features: Grouped notification display (Orders, Tickets, Variants) with collapsible sections, real-time Redux state synchronization, notification type unification with intelligent grouping, read status management with mark-all-as-read functionality, interactive notification items with navigation integration, badge system with unread count display, responsive design with mobile-optimized layout, and comprehensive notification metadata display with timestamp formatting.

Implementation: React functional component with useState for dropdown and group management, Redux integration with useSelector and useDispatch hooks, useEffect for automatic data fetching and state synchronization, Firestore integration for notification CRUD operations, Ant Design Dropdown with custom menu items, comprehensive notification styling with color-coded categories, automatic navigation with React Router integration, and real-time notification updates with background synchronization.

Publish3DAssetsModal.js​

Purpose: Enterprise-grade 3D asset publishing system with batch variant management, library integration, and comprehensive catalog order status tracking for production workflow automation.

Key Features: Batch variant selection with product grouping, expandable table interface with variant details, image processing with white background removal, publication status tracking with Firebase integration, catalog order status automation, comprehensive variant metadata management, progress tracking with loading states, and automatic library synchronization with availability updates.

Implementation: React functional component with useState for selection and processing states, Firestore integration with complex queries and batch updates, custom image processing with canvas manipulation, Table component with expandable rows and custom columns, Promise.all for batch operations, comprehensive error handling with rollback mechanisms, automatic status updates with timestamp tracking, and notification system integration for user feedback.

TypeOfModellingModal.js​

Purpose: Modeling type selection modal for variant processing workflow with predefined options and optional note functionality for production tracking and quality assurance documentation.

Key Features: Predefined modeling type selection (Instaload, Manual, Instaload + Manual), optional modeling notes with TextArea input, form validation with required field checking, automatic data formatting with empty note handling, tooltip integration for user guidance, and clean modal interface with consistent styling.

Implementation: React functional component with useState for form data management, MediumModal wrapper with custom content, Select component with predefined options, TextArea component for note input, comprehensive form validation with trim functionality, automatic data object creation with explicit field mapping, and error handling with user feedback notifications.

VariantAssignedToModal.js​

Purpose: Single variant assignment modal with modeler selection, brand access management, automatic notification creation, and comprehensive assignment tracking for workflow management.

Key Features: Modeler profile fetching with role-based filtering (Modellista, ModellerSupervisor), automatic brand access granting with profile updates, assignment logging with timestamp tracking, notification system integration for assignee alerts, catalog order status automation, current assignment display with user profile resolution, and comprehensive error handling with rollback mechanisms.

Implementation: React functional component with useState for assignment data and loading states, useEffect for profile fetching and data initialization, Firestore integration with complex queries and document updates, user profile resolution with case-insensitive matching, automatic brand access management with list updates, comprehensive logging with LogVariantService integration, notification creation with NotificationService, and automatic catalog order status updates.

VariantsAssignedToModal.js​

Purpose: Bulk variant assignment modal for batch modeler assignment with comprehensive error handling, brand access management, and notification system integration for efficient workflow management.

Key Features: Batch variant assignment with individual error tracking, modeler profile selection with role-based filtering, automatic brand access granting for new users, individual variant logging with comprehensive tracking, batch notification creation for all assignments, progress tracking with partial success handling, and comprehensive error reporting with detailed feedback.

Implementation: React functional component with useState for assignment data and progress tracking, useEffect for modeler profile fetching, Firestore integration with batch document updates, Promise.all for parallel processing with error isolation, comprehensive error tracking with individual variant handling, automatic brand access management with profile updates, batch notification creation with NotificationService integration, and detailed success/error reporting with user feedback notifications.

Application Pages (pages/)​

DownloadLog.js​

Purpose: Advanced Excel report generation system for modeler work logs with comprehensive time tracking, holiday calculations, and detailed analytics for production workflow monitoring.

Key Features: Sophisticated work time calculation respecting Italian business hours (9:00-18:00) with lunch break (13:30-14:30), automatic Italian holiday detection with Easter calculation algorithm, weekend exclusion from work time calculations, comprehensive Excel report generation with multiple sheets per modeler, advanced image compression for file uploads, Firebase Storage integration with organized path structure, detailed statistics including total glasses, decline counts by source, and first validation time tracking.

Implementation: React functional component with useState for modal and loading management, complex work time calculation algorithms with holiday and weekend handling, XLSX library integration for Excel generation with custom styling and formatting, Firestore integration with date range queries and modeler filtering, comprehensive error handling with user feedback notifications, and automatic file naming with timestamp formatting for organized asset management.

Home.js​

Purpose: Main dashboard interface for catalog order management with comprehensive batch tracking, asset status monitoring, and visual progress indicators for the Frame Validation workflow.

Key Features: Dynamic catalog order filtering by user permissions and status, dual view modes (card and row layouts) with persistent preferences, real-time asset status counting with color-coded indicators, comprehensive image management with crop and positioning capabilities, inline order name editing with immediate Firebase updates, role-based access control for different user types, integrated navigation to detailed views and logging systems, and advanced Excel report generation for batch summaries.

Implementation: React functional component with useState for view management and editing states, useEffect for data fetching and profile loading, Firebase integration with complex queries for catalog orders and variants, image upload system with Firebase Storage and positioning modal, comprehensive role-based UI rendering with conditional components, real-time status calculation from variant data, and integrated report generation with detailed analytics.

Log.js​

Purpose: Comprehensive logging and analytics interface for variant validation tracking with advanced filtering, search capabilities, and detailed work time analysis for production monitoring.

Key Features: Advanced date range filtering with current month default and custom range selection, modeler-specific filtering with automatic selection for modeler roles, comprehensive search functionality by product name and SKU, real-time status counting with categorized summaries (Complete, Pending, Declined by Spaarkly/Client), sophisticated work time calculation excluding weekends and Italian holidays, detailed tabular view with sortable columns and pagination, integrated Excel export functionality with DownloadLog component, and role-based access control for data visibility.

Implementation: React functional component with useState for filtering and search management, useMemo for performance optimization of filtered data, complex Firestore queries with timestamp range filtering, advanced work time calculation algorithms respecting business hours and holidays, Ant Design Table integration with custom column rendering and sorting, comprehensive error handling with user feedback, and Redux integration for user role management.

Notifications.js​

Purpose: Advanced notification management system with intelligent grouping, real-time updates, and comprehensive notification lifecycle management for enhanced user communication and workflow tracking.

Key Features: Intelligent notification grouping by type (Variants, Orders, Tickets) with collapsible sections, real-time notification fetching with Redux state management, comprehensive notification enrichment with order and profile data, advanced filtering and search capabilities with unread status tracking, interactive notification handling with automatic read status updates, detailed notification content display with contextual information, integrated navigation to relevant pages based on notification type, and batch operations for marking all notifications as read.

Implementation: React functional component with Redux integration for notification state management, useEffect for data fetching and profile enrichment, comprehensive Firestore integration for brand and profile data retrieval, advanced notification processing with type-based categorization, dynamic UI rendering with collapsible groups and status indicators, automatic scroll functionality for notification navigation, and comprehensive error handling with user feedback notifications.

Products.js​

Purpose: Comprehensive product catalog interface with advanced search, filtering, and progress tracking capabilities for managing 3D eyewear assets within catalog orders.

Key Features: Dynamic product grid with responsive layout and progress indicators, advanced search functionality with real-time highlighting and filtering, comprehensive image management with upload, crop, and background removal capabilities, detailed progress tracking with visual indicators and completion percentages, integrated navigation to variant details and product management, role-based access control with editing permissions, real-time data synchronization with Firebase, and comprehensive error handling with user feedback.

Implementation: React functional component with useState for search and editing management, useEffect for data fetching and image processing, Firebase integration with complex queries for products and variants, advanced image processing with background removal algorithms, Canvas API integration for image manipulation and placeholder generation, comprehensive search algorithms with text highlighting, and integrated modal systems for image positioning and editing.

ReportBrand.js​

Purpose: Specialized Excel report generation utility for brand-specific catalog order summaries with detailed asset breakdowns and comprehensive analytics for client reporting.

Key Features: Automated Excel workbook generation with professional formatting and styling, comprehensive catalog order data aggregation with asset status breakdowns, detailed client information integration with profile data, advanced asset counting with status-specific categorization, automatic file naming with timestamp formatting, and comprehensive error handling with user feedback notifications.

Implementation: Utility function with XLSX library integration for Excel generation, comprehensive data processing algorithms for catalog order analysis, advanced styling and formatting for professional report presentation, automatic file download functionality with browser compatibility, and comprehensive error handling with detailed logging for debugging and user feedback.

VariantDetails.js​

Purpose: Comprehensive variant management interface with detailed asset information, status tracking, validation workflows, and advanced 3D model management for individual eyewear variants.

Key Features: Detailed variant information display with comprehensive metadata, advanced 3D model management with USDZ generation and thumbnail processing, sophisticated status workflow management with validation and decline capabilities, comprehensive image gallery with upload and management capabilities, integrated color management with hex code editing and validation, advanced URL management for 3D assets with validation and update capabilities, role-based access control with editing permissions, real-time data synchronization with Firebase, and comprehensive navigation with unsaved changes protection.

Implementation: React functional component with complex state management for editing and validation, useEffect for data fetching and image processing, Firebase integration with real-time updates and file management, advanced 3D model processing with thumbnail generation, comprehensive form validation with unsaved changes detection, integrated modal systems for various editing workflows, and advanced error handling with user feedback and confirmation dialogs.

Variants.js​

Purpose: Advanced variant catalog interface with comprehensive filtering, categorization, and management capabilities for organizing and tracking multiple eyewear variants within product collections.

Key Features: Dynamic variant grid with responsive layout and QR code generation, comprehensive filtering by categories, tags, and badges with real-time updates, advanced tag and badge management with creation and assignment capabilities, sophisticated coefficient management for AR platform optimization, integrated category management with CRUD operations, comprehensive search functionality with real-time filtering, role-based access control with editing permissions, and advanced image processing with background removal and placeholder generation.

Implementation: React functional component with complex state management for filtering and editing, useEffect for data fetching and category management, Firebase integration with real-time updates and batch operations, advanced QR code generation with download capabilities, comprehensive modal systems for tag, badge, and category management, Canvas API integration for image processing, and comprehensive error handling with user feedback notifications.

Service Layer (services/)​

CatalogOrderUtils.js​

Purpose: Comprehensive catalog order management utility providing automated status tracking, validation workflows, and completion monitoring for 3D asset production pipelines.

Key Features: Automated catalog order status verification and updates based on variant completion, comprehensive variant tracking with publication status monitoring, intelligent catalog order validation with status and type checking, batch processing capabilities for multiple variant status checks, automatic completion timestamping with Firestore integration, and comprehensive error handling with detailed logging for production monitoring.

Implementation: Utility functions with Firestore integration for catalog order and variant queries, automated status checking algorithms with publication validation, batch processing with Promise-based operations, comprehensive error handling with detailed console logging, and automatic timestamp management for completion tracking and audit trails.

Utils (services/Utils/)​

index.js​

Purpose: Centralized utility export module providing unified access to role permissions, status management, and workflow control functions for the Frame Validation system.

Key Features: Centralized export system for all utility functions, unified access to role-based permissions and status management, comprehensive function organization with logical grouping, simplified import structure for consuming components, and consistent API surface for utility functions across the application.

Implementation: ES6 module exports with centralized import/export pattern, organized function grouping by functionality (permissions, status, workflow), comprehensive function re-export for simplified consumption, and standardized naming conventions for consistent API access.

LogVariantService.js​

Purpose: Comprehensive logging service class for variant lifecycle tracking with detailed audit trails, assignment management, and workflow state transitions for production monitoring and analytics.

Key Features: Complete variant lifecycle logging with creation, assignment, initialization, validation, and decline tracking, automatic log document creation and management with Firestore integration, comprehensive audit trail with timestamp tracking and user attribution, intelligent log retrieval with automatic creation fallback, detailed workflow state tracking with status transitions, product and SKU information synchronization, and comprehensive error handling with detailed logging for debugging and monitoring.

Implementation: Static class methods with Firestore integration for document management, automatic log creation with variant data synchronization, comprehensive timestamp management with Firestore Timestamp objects, intelligent document retrieval with existence validation, detailed error handling with console logging and error propagation, and automatic data enrichment with product and variant information.

NotificationService.js​

Purpose: Advanced notification management service providing intelligent role-based notification distribution, workflow-aware messaging, and comprehensive user communication for variant validation processes.

Key Features: Intelligent role-based notification routing with brand filtering for clients, comprehensive workflow-aware notification creation for assignments, validations, and declines, advanced user targeting with role and brand access validation, automatic notification deduplication and user exclusion logic, detailed notification content with variant and product information, batch notification creation with Promise-based processing, and comprehensive error handling with individual notification failure isolation.

Implementation: Static class methods with Firestore integration for notification management, intelligent role-based user querying with brand access filtering, comprehensive notification data structure with metadata and navigation information, batch processing with Promise.all for parallel notification creation, detailed error handling with individual failure tracking, and automatic user exclusion logic for notification creators.

RolePermissions.js​

Purpose: Comprehensive role-based access control system providing granular permission management, workflow state access validation, and security enforcement for the Frame Validation system.

Key Features: Detailed role-based permission matrix with granular access control for coefficients, 3D assets, tags, badges, and priority management, comprehensive workflow state access validation with role-specific visibility rules, intelligent status mapping between Italian and English workflow states, advanced permission checking with status-specific access control, comprehensive role definitions for Admin, Cliente, Modellista, ModellerSupervisor, Validator, and Guest roles, and flexible permission system supporting future role extensions.

Implementation: Static permission configuration with role-based access matrices, comprehensive status mapping with workflow state translations, functional permission checking with role and status validation, modular permission functions for specific feature access control, and standardized permission API for consistent access control across the application.

StatusAccess.js​

Purpose: Advanced workflow state management system providing intelligent status transitions, role-based action validation, and workflow progression control for variant validation processes.

Key Features: Intelligent status transition logic with role-based workflow progression, comprehensive action validation with role and status-specific rules, advanced workflow state management supporting validate, decline, and start actions, detailed role-specific button state control with disabled state logic, comprehensive workflow progression rules for all user roles (Admin, Cliente, Modellista, ModellerSupervisor, Validator, Guest), and flexible workflow system supporting complex validation hierarchies.

Implementation: Functional workflow management with role and status-based decision trees, comprehensive action validation with role-specific permission checking, intelligent status progression algorithms with workflow state transitions, modular validation functions for button state management, and standardized workflow API for consistent state management across the application.