Frontend Structure

Directory organization and architectural patterns in the MLM CMMS frontend

Overview

The MLM CMMS frontend is a single-page application built with React 19, TypeScript, Vite, and Tailwind CSS v4. The codebase follows a modular architecture with clear separation of concerns.

Directory Structure

Core Application

Root Structure

src/
├── main.tsx                    # Application entry point
├── Routes/                     # Route definitions
├── components/                 # Reusable UI components
├── pages/                      # Page-level components
├── context/                    # React Context providers
├── services/                   # API/data service layer
├── rbac/                       # Role-based access control
├── lib/                        # Utility libraries
├── hooks/                      # Custom React hooks
├── features/                   # Feature-specific modules
├── types/                      # TypeScript type definitions
├── utils/                      # Helper functions
├── assets/                     # Static assets
├── styles/                     # CSS files
├── pwa/                        # Progressive Web App utilities
└── constants/                  # Application constants

Key Directories

components/

Reusable UI components organized by domain:

• ui/ - Base UI primitives (buttons, inputs, modals)
• layout/ - Layout components (headers, sidebars)
• navigation/ - Navigation components
• common/ - Shared components
• dashboard/ - Dashboard-specific components
• reports/ - Reporting components

pages/

Page-level components mapped to routes:

• admin/ - Administration pages
• inventory/ - Inventory management pages
• Lazy-loaded for performance

services/

Data access layer:

• ticketService.ts - Ticket operations
• userService.ts - User management
• inventory/ - Inventory services
• All Supabase interactions happen here

context/

Global state management:

• AuthContext.tsx - Authentication state
• UserContext.tsx - User profile data
• PermissionsContext.tsx - RBAC permissions
• SettingsContext.tsx - Application settings

Application Bootstrap

The application initializes through main.tsx with a nested provider structure:

1. Entry Point

   main.tsx sets up the React root and configures global behaviors

   src/main.tsx

   ReactDOM.createRoot(document.getElementById('root')!).render(
     <React.StrictMode>
       <ThemeProvider>
         <AuthProvider>
           <UserProvider>
             <AssigneeProvider>
               <BrowserRouter>
                 <PermissionsProvider>
                   <SettingsProvider>
                     <BrandingProvider>
                       <ThemedAppRoot />
                     </BrandingProvider>
                   </SettingsProvider>
                 </PermissionsProvider>
               </BrowserRouter>
             </AssigneeProvider>
           </UserProvider>
         </AuthProvider>
       </ThemeProvider>
     </React.StrictMode>
   );
   
2. Global Listeners

   Numeric input normalization and PWA install prompt capture:

   src/main.tsx

   setupGlobalNumericInputNormalization();
   setupGlobalInstallPromptCapture();
   
3. Service Worker Registration

   In production, registers the service worker for offline support:

   src/main.tsx

   if (import.meta.env.PROD && 'serviceWorker' in navigator) {
     window.addEventListener('load', () => {
       const swUrl = `/sw.js?v=${encodeURIComponent(__APP_VERSION__)}`;
       navigator.serviceWorker.register(swUrl, { updateViaCache: 'none' })
     });
   }
   

Code Organization Patterns

Component Hierarchy

ThemedAppRoot
└── AppRouterContent
    ├── ProtectedRoute (wraps authenticated routes)
    │   └── RequirePerm (checks permissions)
    │       └── Page Component
    └── Public Routes (login, 403, etc.)

Feature Modules

Complex features are organized into dedicated modules:

features/
├── tickets/
│   ├── workRequestsFilters.ts
│   └── [ticket-specific logic]
└── management/
    └── [management features]

Feature modules encapsulate domain-specific logic, keeping page components clean and focused.

Type Definitions

TypeScript types are centralized in types/ directory:

Core Types

types/Ticket.ts

export type Ticket = {
  id: number;
  title: string;
  status: 'Pendiente' | 'En Ejecución' | 'Finalizadas';
  priority: string;
  created_by: string;
  is_archived: boolean;
  // ...
};

Inventory Types

types/inventory/
├── master.ts       # Core inventory entities
├── docs.ts         # Document types
├── stock.ts        # Stock management
├── ledger.ts       # Transaction ledger
└── views.ts        # View definitions

Environment Configuration

Frontend environment variables are prefixed with VITE_:

.env.example

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key
VITE_WEB_PUSH_PUBLIC_KEY=your-vapid-public-key
VITE_APP_ENV=development
VITE_ENABLE_REMOTE_REPORT_LAYOUT=false

Never expose SUPABASE_SERVICE_ROLE_KEY in the frontend. Only the anon key should be used.

Build Output

The Vite build produces:

• Lazy-loaded chunks for each route
• Optimized assets with content hashing
• Service worker for PWA capabilities
• Manifest for installation

npm run build
# Output: dist/

Next Steps

Routing

Learn about route configuration and navigation

Services

Understand the data access layer

Components

Explore the component library