# mbwk25/optimum-solutions-group architecture

> Architecture diagram of the GitHub repository mbwk25/optimum-solutions-group, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mbwk25/optimum-solutions-group
- Repository: https://github.com/mbwk25/optimum-solutions-group

## Overview

##### Project type and purpose
- This is a single-page application (SPA) built with Vite, React, TypeScript, Tailwind CSS, and shadcn-ui.
- There is no separate backend in this repo—data may be fetched from external APIs or serverless endpoints.
- The purpose is to serve a portfolio/site with various feature sections (About, Contact, IoT Solutions, etc.).

##### Top-level architectural components
- Developer Workstation/IDE
– Local Git clone, Node.js & npm environment
– Vite development server (hot-reload)
- Source Code
– src/main.tsx (entry point) & index.html (template)
– Feature modules under src/features/*
– Shared components, hooks, utils under src/shared/*
– UI primitives under src/shared/ui (shadcn-ui + custom)
– Static assets under src/assets & public/
- Build System
– Vite bundler (vite.config.ts) produces optimized static assets (JS/CSS)
– Tailwind CSS processor (tailwind.config.ts + postcss.config.mjs)
- Testing
– Jest + ts-jest + React Testing Library + jest-dom
– Test files in __tests__ alongside components, global setup in src/setupTests.ts
- Deployment / Hosting
– Lovable platform: triggers on git push or manual “Publish”
– Deployed as static site on CDN (with optional custom domain)
- Client / Browser
– Loads index.html → bundles → hydrates React SPA
– Interactions handled by React components/hooks

##### Mapping relationships and data flow
- Developer commits code → Git repo → Lovable CI/CD (or local npm run dev)
→ Vite builds → static assets → CDN/Hosting
- Browser requests index.html → bundles → React renders feature & shared components
- Components call shared hooks/utils for analytics, performance budgeting, SEO, etc.
- Optional external services (e.g., analytics endpoint, contact form API).

##### Architectural patterns and design principles
- Component-based architecture: features vs. shared
- Feature modularization: one folder per site section
- Shared UI primitives (buttons, cards, dialogs) follow Atomic/Design System pattern
- Hook-based logic extraction (useInput, useToast, usePerformanceMonitor)
- CSS-in-JS separation: Tailwind utility classes + critical CSS prefetch

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Development
    Dev["Developer Workstation"]:::devOps
    Git["Version Control (GitHub/Lovable)"]:::devOps
    CI["CI/CD Pipeline"]:::devOps

    Dev -->|"commit code"| Git
    Git -->|"trigger"| CI

    %% Build System
    subgraph "Build System" 
        ViteDev["Vite Dev Server"]:::code
        ViteProd["Vite Production Bundler"]:::code
        Tailwind["Tailwind Processor"]:::code
        Config["Build Configs"]:::code
        Config --> ViteProd
        Config --> Tailwind

        click Config "https://github.com/mbwk25/optimum-solutions-group/blob/main/vite.config.ts"
        click Config "https://github.com/mbwk25/optimum-solutions-group/blob/main/tailwind.config.ts"
        click Config "https://github.com/mbwk25/optimum-solutions-group/blob/main/postcss.config.mjs"
    end
    CI -->|"npm run build"| ViteProd
    CI -->|"npm run build"| Tailwind

    %% Hosting
    CDN["Lovable CDN Hosting"]:::runtime

    ViteProd -->|"deploy static assets"| CDN

    %% Source Code
    subgraph "Source Code" 
        subgraph "Entry Points"
            HTML["index.html"]:::code
            Main["src/main.tsx"]:::code
            click HTML "https://github.com/mbwk25/optimum-solutions-group/blob/main/index.html"
            click Main "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/main.tsx"
        end

        subgraph "Feature Modules"
            About["AboutSection.tsx"]:::code
            Contact["ContactSection.tsx"]:::code
            Hero["HeroSection.tsx"]:::code
            IoT["IoTSection.tsx"]:::code
            Navigation["Navigation.tsx"]:::code
            Portfolio["PortfolioSection.tsx"]:::code
            Services["ServicesSection.tsx"]:::code
            Testimonials["TestimonialsSection.tsx"]:::code

            click About "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/features/about/AboutSection.tsx"
            click Contact "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/features/contact/ContactSection.tsx"
            click Hero "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/features/hero/HeroSection.tsx"
            click IoT "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/features/iot-solutions/IoTSection.tsx"
            click Navigation "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/features/navigation/Navigation.tsx"
            click Portfolio "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/features/portfolio/PortfolioSection.tsx"
            click Services "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/features/services/ServicesSection.tsx"
            click Testimonials "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/features/testimonials/TestimonialsSection.tsx"
        end

        subgraph "Shared Components"
            BackToTop["BackToTop.tsx"]:::code
            CriticalCSS["CriticalCSS.tsx"]:::code
            CustomCursor["CustomCursor.tsx"]:::code
            ErrorBoundary["ErrorBoundary.tsx"]:::code
            FAQ["FAQSection.tsx"]:::code
            Footer["Footer.tsx"]:::code
            LazyImage["LazyImage.tsx"]:::code
            Loading["LoadingScreen.tsx"]:::code
            Particle["ParticleSystem.tsx"]:::code
            PerfOpt["PerformanceOptimizer.tsx"]:::code
            Estimator["ProjectEstimator.tsx"]:::code
            Prefetcher["ResourcePrefetcher.tsx"]:::code
            SEOHead["SEOHead.tsx"]:::code

            click BackToTop "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/components/BackToTop.tsx"
            click CriticalCSS "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/components/CriticalCSS.tsx"
            click CustomCursor "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/components/CustomCursor.tsx"
            click ErrorBoundary "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/components/ErrorBoundary.tsx"
            click FAQ "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/components/FAQSection.tsx"
            click Footer "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/components/Footer.tsx"
            click LazyImage "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/components/LazyImage.tsx"
            click Loading "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/components/LoadingScreen.tsx"
            click Particle "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/components/ParticleSystem.tsx"
            click PerfOpt "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/components/PerformanceOptimizer.tsx"
            click Estimator "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/components/ProjectEstimator.tsx"
            click Prefetcher "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/components/ResourcePrefetcher.tsx"
            click SEOHead "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/components/optimized/SEOHead.tsx"
        end

        subgraph "Shared Hooks"
            Hook1["use-mobile.tsx"]:::code
            Hook2["use-toast.ts"]:::code
            Hook3["useErrorHandler.ts"]:::code
            Hook4["usePerformanceMonitor.ts"]:::code
            Hook5["useScrollAnimation.ts"]:::code
            Hook6["useServiceWorker.ts"]:::code

            click Hook1 "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/hooks/use-mobile.tsx"
            click Hook2 "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/hooks/use-toast.ts"
            click Hook3 "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/hooks/useErrorHandler.ts"
            click Hook4 "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/hooks/usePerformanceMonitor.ts"
            click Hook5 "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/hooks/useScrollAnimation.ts"
            click Hook6 "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/hooks/useServiceWorker.ts"
        end

        subgraph "Shared UI Primitives"
            UI["src/shared/ui"]:::code
            click UI "https://github.com/mbwk25/optimum-solutions-group/tree/main/src/shared/ui"
        end

        subgraph "Shared Utilities"
            Utils1["analytics.ts"]:::code
            Utils2["debounce.ts"]:::code
            Utils3["errorHandler.ts"]:::code
            Utils4["performanceBudget.ts"]:::code
            Utils5["seo.ts"]:::code
            Utils6["utils.ts"]:::code

            click Utils1 "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/utils/analytics.ts"
            click Utils2 "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/utils/debounce.ts"
            click Utils3 "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/utils/errorHandler.ts"
            click Utils4 "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/utils/performanceBudget.ts"
            click Utils5 "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/utils/seo.ts"
            click Utils6 "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/utils/utils.ts"
        end

        subgraph "Static Assets"
            Public["public/"]:::code
            Assets["src/assets/"]:::code
            click Public "https://github.com/mbwk25/optimum-solutions-group/blob/main/public/robots.txt"
            click Public "https://github.com/mbwk25/optimum-solutions-group/blob/main/public/sw.js"
            click Assets "https://github.com/mbwk25/optimum-solutions-group/tree/main/src/assets/"
        end

        subgraph "Testing Suite"
            JestConfig["jest.config.mjs"]:::code
            SetupTests["src/setupTests.ts"]:::code
            TestFile["Button.test.tsx"]:::code
            click JestConfig "https://github.com/mbwk25/optimum-solutions-group/blob/main/jest.config.mjs"
            click SetupTests "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/setupTests.ts"
            click TestFile "https://github.com/mbwk25/optimum-solutions-group/blob/main/src/shared/ui/__tests__/Button.test.tsx"
        end

        subgraph "Package & Scripts"
            Package["package.json"]:::code
            TSConfig["tsconfig.json"]:::code
            Babel["babel.config.js"]:::code
            ESLint["eslint.config.js"]:::code

            click Package "https://github.com/mbwk25/optimum-solutions-group/blob/main/package.json"
            click TSConfig "https://github.com/mbwk25/optimum-solutions-group/blob/main/tsconfig.json"
            click Babel "https://github.com/mbwk25/optimum-solutions-group/blob/main/babel.config.js"
            click ESLint "https://github.com/mbwk25/optimum-solutions-group/blob/main/eslint.config.js"
        end
    end

    CI -->|"test code"| Source_Code

    %% Runtime
    Browser["Browser / Client"]:::runtime
    External["External Services"]:::external

    CDN --> Browser
    Browser -->|"fetch API"| External
    External -->|"respond"| Browser

    classDef devOps fill:#f0f8ff,stroke:#4682b4;
    classDef code fill:#fffafa,stroke:#ff69b4;
    classDef runtime fill:#f5fffa,stroke:#32cd32;
    classDef external fill:#f5f5dc,stroke:#daa520;
```
