Folder Structure

Author: Carmine Antonio Bonavoglia Creation Date: 29/10/2025
Last Reviewer: Carmine Antonio Bonavoglia Last Updated: 30/10/2025

The ARShades Studio project follows a structured, scalable architecture designed to separate concerns and facilitate maintainability. This document outlines the directory hierarchy and explains the purpose of each major folder within the application.

Project Tree Structure

ARShades_Studio_V2/
├── src/
│   ├── assets/
│   │   ├── file/
│   │   ├── fonts/
│   │   ├── hdr/
│   │   ├── icon/
│   │   ├── images/
│   │   └── lottie/
│   ├── components/
│   │   ├── AR3dViewer/
│   │   ├── ARSCatalog/
│   │   ├── ARShades3dViewerCustomThree/
│   │   ├── Admin/
│   │   ├── Analytics/
│   │   ├── Components/
│   │   ├── DataConsumption/
│   │   ├── Gateways/
│   │   ├── Home/
│   │   ├── LocalRenderer/
│   │   ├── Login/
│   │   ├── ModelViewer/
│   │   ├── MyCatalogues/
│   │   ├── OrderPage/
│   │   ├── ProductDetail/
│   │   │   ├── VariantDetails/
│   │   │   ├── VariantsList/
│   │   │   ├── VirtualTryOn/
│   │   │   └── hooks/
│   │   ├── Profile/
│   │   ├── SupportModal.js
│   │   ├── ThumbnailGenerator/
│   │   ├── CenteredLoader.js
│   │   ├── DashboardLayout.js
│   │   ├── EmptyCard.js
│   │   ├── ErrorBoundary.js
│   │   └── PrivateRoute.js
│   ├── config/
│   │   ├── firebase.js
│   │   └── version.js
│   ├── data/
│   │   ├── analytics/
│   │   ├── chat/
│   │   ├── customizer/
│   │   ├── ecommerce/
│   │   ├── email/
│   │   ├── todo/
│   │   ├── base.js
│   │   └── utils.js
│   ├── frameValidation/
│   │   ├── modal/
│   │   ├── pages/
│   │   └── services/
│   ├── hooks/
│   │   └── useTrackedImageLoad.js
│   ├── models/
│   ├── pages/
│   │   ├── AR3dViewer.js
│   │   ├── ARSCatalog.js
│   │   ├── ARSCatalogSPA.js
│   │   ├── ARSProductDetail.js
│   │   ├── ARShades3dViewer.js
│   │   ├── Admin.js
│   │   ├── Analytics.js
│   │   ├── CatalogueDetail.js
│   │   ├── CompleteRegistration.js
│   │   ├── Components.js
│   │   ├── DataConsumption.js
│   │   ├── FrameValidation.js
│   │   ├── Gateways.js
│   │   ├── Home.js
│   │   ├── Login.js
│   │   ├── MaterialPresets.js
│   │   ├── MyCatalogues.js
│   │   ├── OrderPage.js
│   │   ├── Profile.js
│   │   ├── Renderer.js
│   │   └── [additional page components]
│   ├── redux/
│   │   ├── Catalogues/
│   │   ├── MainBrands/
│   │   ├── Profiles/
│   │   ├── actionType.js
│   │   ├── analytics/
│   │   ├── authentication/
│   │   ├── brand/
│   │   ├── brandViewer/
│   │   ├── cart/
│   │   ├── catalog/
│   │   ├── chat-app/
│   │   ├── config/
│   │   ├── customizer/
│   │   ├── email-app/
│   │   ├── filter/
│   │   ├── index.js
│   │   ├── licenses/
│   │   ├── model/
│   │   ├── notifications/
│   │   ├── occhiale/
│   │   ├── product/
│   │   ├── profile/
│   │   ├── rootReducer.js
│   │   ├── selectors/
│   │   ├── selectors.js
│   │   ├── service/
│   │   ├── sidebar.js
│   │   ├── slices/
│   │   ├── store.js
│   │   ├── theme/
│   │   ├── todo/
│   │   └── wishlist/
│   ├── route/
│   │   └── ProtectedRoute.js
│   ├── services/
│   │   ├── api/
│   │   ├── cache/
│   │   ├── data/
│   │   ├── firebase/
│   │   ├── hooks/
│   │   ├── utils/
│   │   ├── OnBordingUtils.js
│   │   ├── catalogueService.js
│   │   ├── edit3dViewer.js
│   │   ├── emailService.js
│   │   ├── home.js
│   │   └── profile.js
│   ├── styles/
│   │   ├── ARShades3dViewerCustom/
│   │   ├── ARShades3dsTemplate/
│   │   ├── ARShadesDemo/
│   │   ├── Dashboard/
│   │   ├── FrameValidation/
│   │   ├── Home/
│   │   └── ModelViewer/
│   ├── theme/
│   │   ├── ThemeContext.js
│   │   ├── ThemeToggle.js
│   │   ├── brandColors.js
│   │   └── theme.js
│   ├── utils/
│   │   ├── catalogEvents.js
│   │   ├── notifications.js
│   │   ├── numberFormatting.js
│   │   └── secureStorage.js
│   ├── docs/
│   ├── App.css
│   ├── App.js
│   ├── App.test.js
│   ├── chartSetup.js
│   ├── fonts.css
│   ├── index.css
│   ├── index.js
│   ├── logo.svg
│   ├── reportWebVitals.js
│   └── setupTests.js
├── public/
│   ├── index.html
│   ├── manifest.json
│   ├── robots.txt
│   └── fonts/
│       └── atkinson/
├── build/
│   ├── asset-manifest.json
│   ├── index.html
│   ├── manifest.json
│   ├── robots.txt
│   ├── fonts/
│   │   └── atkinson/
│   └── static/
│       ├── css/
│       ├── js/
│       └── media/
├── docs/
├── firebase.json
├── package.json
├── README.md
└── update-version.js

Directory Overview

Root Level Configuration Files

• package.json – Node.js project metadata, dependencies, and npm scripts for build and development
• README.md – Project overview, setup instructions, and quick-start guide

/src – Application Source Code

The heart of the application, containing all React components, logic, and utilities organised by concern and feature domain.

/src/assets – Static Resources

All static assets imported directly into the application code:

• file/ – Downloadable documents and reference files
• fonts/ – Custom font files including the Atkinson font family
• hdr/ – High Dynamic Range imagery for advanced 3D rendering and lighting
• icon/ – SVG and raster icon assets used throughout the UI
• images/ – Product photography, brand assets, and UI imagery
• lottie/ – Animated JSON files for Lottie animation library integration

/src/components – Reusable React Components

Modular React components organised by feature domain. Each folder typically contains related components, subcomponents, styles, and component-specific utilities.

Major Components:

• ProductDetail/ – Unified product display and management interface

  • VariantDetails/ – Individual variant validation and 3D preview
  • VariantsList/ – Variant list rendering with filtering and sorting
  • VirtualTryOn/ – Augmented reality virtual try-on functionality
  • hooks/ – Custom hooks specific to product detail workflows

• AR3dViewer/ – Augmented reality viewer for immersive eyewear preview

• ModelViewer/ – WebGL/Three.js 3D model viewing and manipulation

• Admin/ – Administrative dashboard and management tools

• Analytics/ – Analytics dashboards and data visualisation

• Login/ – Authentication and login interface

• Profile/ – User account and profile management

• Home/ – Home page sections and hero components

• ARSCatalog/ – Catalogue browsing and product discovery

• MyCatalogues/ – User-owned catalogue management interface

• OrderPage/ – Order creation, management, and checkout flow

• DataConsumption/ – Data usage tracking and reporting

• Gateways/ – Payment gateway and third-party integration components

• ThumbnailGenerator/ – Thumbnail generation utilities and components

Utility Components:

• CenteredLoader.js – Centralised loading spinner component
• DashboardLayout.js – Reusable dashboard grid and layout wrapper
• EmptyCard.js – Empty state placeholder component
• ErrorBoundary.js – React error boundary for error handling
• SupportModal.js – Customer support and help modal
• PrivateRoute.js – Route protection component (authentication guard)

/src/config – Configuration Management

Environment and feature configuration files:

• firebase.js – Firebase SDK initialisation with authentication and database setup
• version.js – Application version constants and version-related metadata

/src/data – Mock Data and Fixtures

Curated mock data sets used during development and for feature demonstrations:

• analytics/ – Sample analytics data and metrics
• chat/ – Chat message templates and conversation fixtures
• customizer/ – Customiser option defaults and presets
• ecommerce/ – Mock product and order data
• email/ – Email template and notification fixtures
• todo/ – Task and todo list samples
• base.js – Base data structures and common fixtures
• utils.js – Data manipulation and transformation utilities

/src/frameValidation – Frame Validation Module

Dedicated feature module for the Frame Validation system, handling batch validation, quality assurance, and assignment management for 3D eyewear production:

• pages/ – Page-level components for the validation workflow
• modal/ – Modal dialogs for batch operations and validations
• services/ – Business logic, API integration, and orchestration

/src/hooks – Custom React Hooks

Reusable React hooks encapsulating complex logic for use across multiple components:

• useTrackedImageLoad.js – Hook for tracking and managing image loading states with callbacks

/src/models – Type Definitions and Models

Placeholder directory reserved for future TypeScript type definitions, PropTypes, and domain model classes (currently empty).

/src/pages – Route-Level Page Components

Top-level page components representing primary application routes and views. Each page typically orchestrates feature components and manages data loading for that route:

• AR3dViewer.js – Augmented reality viewer page
• Admin.js – Administrator control panel and system management
• Analytics.js – Analytics dashboard and reporting
• FrameValidation.js – Frame validation workflow entry point
• Home.js – Landing and home page
• Login.js – Authentication and user login
• ARSCatalog.js – Main catalogue browsing interface
• MyCatalogues.js – User catalogue management page
• OrderPage.js – Order management and checkout interface
• Profile.js – User profile and account settings
• DataConsumption.js – Data usage analytics page
• CatalogueDetail.js – Individual catalogue detail and editing
• Gateways.js – Payment and gateway integration interface

/src/redux – Global State Management

Redux store configuration, state slices, and selectors for centralised application state:

• store.js – Redux store configuration and middleware setup
• rootReducer.js – Combined root reducer aggregating all slices
• actionType.js – Redux action type constants
• selectors.js – Memoised state selectors for efficient component subscriptions
• slices/ – Redux Toolkit slices for modular state management

State Domains:

• authentication/ – User login, session, and auth token state
• brand/ – Brand information and brand-specific configurations
• brandViewer/ – Brand viewer state and preferences
• catalog/ – Product catalogue and listing state
• product/ – Product details and related metadata
• cart/ – Shopping cart and order line items
• profile/ – User profile and account information
• notifications/ – Application notifications and alerts
• analytics/ – Analytics data and dashboard state
• filter/ – Search filters and sorting preferences
• customizer/ – Customiser settings and user selections
• Catalogues/ – User-owned catalogues collection
• MainBrands/ – Main brand registry and metadata
• Profiles/ – User profiles collection
• licenses/ – Licensing and subscription state

/src/route – Routing and Route Guards

Navigation configuration and route protection components:

• ProtectedRoute.js – Route guard component enforcing authentication before access

/src/services – API and Data Access Layer

Centralised data-access and external service integration layer, keeping API calls and external operations separate from UI components:

• api/ – REST API client and endpoint definitions
• firebase/ – Firebase Realtime Database operations and Cloud Functions integration
• cache/ – Client-side caching strategies and cache management
• data/ – Data fetching, transformation, and pagination utilities
• hooks/ – Custom hooks for service integration and data fetching
• utils/ – Service-related utility functions
• catalogueService.js – Catalogue CRUD operations and management
• emailService.js – Email sending and notification dispatch
• profile.js – User profile API operations
• home.js – Home page data and content services
• edit3dViewer.js – 3D model editing and manipulation services
• OnBordingUtils.js – User onboarding flow and first-time setup utilities

/src/styles – CSS Modules and Style Sheets

Organised CSS and styling modules, typically paired with corresponding component directories:

• ARShades3dViewerCustom/ – 3D viewer and AR preview styles
• Dashboard/ – Dashboard layout and component styling
• FrameValidation/ – Frame validation interface and workflow styles
• Home/ – Home page and landing page styling
• ModelViewer/ – WebGL model viewer styling
• ARShadesDemo/ – Demo component and showcase styling
• ARShades3dsTemplate/ – Template and template preview styling

/src/theme – Design Tokens and Theme Configuration

Centralised theme configuration enabling consistent UI/UX and easy theme switching:

• theme.js – Primary theme definitions including colours, typography, spacing, and component variants
• brandColors.js – Brand-specific colour palettes and brand identity constants
• ThemeContext.js – React Context API for theme state management
• ThemeToggle.js – Theme switching component and provider

/src/utils – Utility Functions

General-purpose utility functions and helpers used across the application:

• catalogEvents.js – Catalogue event tracking, analytics, and event handlers
• notifications.js – Notification formatting, queuing, and display utilities
• numberFormatting.js – Number, currency, and numeric value formatting utilities
• secureStorage.js – Secure local storage operations with encryption support

/src – Root Level Files

• App.js – Application root component managing routing and providers
• App.css – Global application styles
• index.js – React application entry point and ReactDOM rendering
• index.css – Global CSS reset and base styling
• chartSetup.js – Chart.js configuration and theme setup
• fonts.css – Font face declarations and font loading
• logo.svg – Application logo asset
• setupTests.js – Jest and testing library configuration
• reportWebVitals.js – Web performance metrics reporting
• App.test.js – Root component tests

/public – Static Files

Publicly accessible static files served directly by the web server without processing:

• index.html – Main HTML entry point and SPA shell
• manifest.json – Progressive Web App manifest for PWA capabilities
• robots.txt – SEO robots configuration and crawling rules
• fonts/ – Publicly accessible font files

/build – Production Build Artefacts

Compiled, production-ready application bundle generated by the React build pipeline. Automatically recreated during deployment and not committed to version control.

• index.html – Minified HTML with bundled scripts
• static/css/ – Minified CSS bundles
• static/js/ – Minified JavaScript bundles
• static/media/ – Processed media assets
• asset-manifest.json – Asset to file mapping for caching strategies

/backups – Version Backups

Date-stamped and version-numbered snapshots for quick rollback and production archaeology:

• Date-stamped folders (e.g., 01. 01-09-2025/) – Chronological backup snapshots
• Version-numbered folders (e.g., 2.5.0/, 2.5.1/) – Tagged release versions
• Prod/ – Current production build snapshot for immediate reference

/docs – Project Documentation

Docusaurus-based documentation site explaining product workflows, architecture decisions, operational playbooks, and troubleshooting guides.

Architecture Principles

Feature-Based Organisation – Components and logic are grouped by feature or domain rather than by file type, enabling independent feature development, testing, and scaling.

Service Layer Abstraction – All external API calls, Firebase operations, and third-party integrations are centralised in the /services directory, maintaining clear separation between data access and presentation logic.

Centralised State Management – Redux store is organised into logical slices, each managing a specific domain (authentication, products, cart, notifications, etc.) with corresponding selectors for efficient component subscriptions.

Reusable Hooks – Custom React hooks encapsulate complex logic and state management, promoting code reuse and reducing component complexity.

Theme Separation – Theming logic and design tokens are isolated in the /theme directory, enabling consistent styling and effortless brand customisation across the entire application.

Utility Consolidation – Helper functions are grouped logically by concern, promoting code reuse, maintainability, and a single source of truth for cross-cutting logic.

Modular 3D Integration – 3D viewing, AR capabilities, and model manipulation are encapsulated in dedicated components and services, keeping complex WebGL logic separate from business logic.

Development Workflow

Adding Routes – Create a new page component in /src/pages, then import and register in the application router within App.js.

Creating Feature Components – Organise related components in a feature folder under /src/components, including subcomponents, styles, and component-specific hooks.

Integrating External APIs – Implement API calls in /src/services/api/ or /src/services/firebase/, then export service functions for use in components or Redux slices.

Extending State Management – Create new Redux slices in /src/redux/slices/, add corresponding selectors in /src/redux/selectors/, then integrate into rootReducer.js.

Adding Static Assets – Place imported assets in /src/assets/ and publicly served assets (favicons, manifests) in /public/.

Styling Approaches – Use themed CSS modules in /src/styles/, import global styles in components, or apply theme tokens from /src/theme/ for consistent branding.

This structure supports scalability, maintainability, and clear separation of concerns throughout the ARShades Studio application.