# marcoscarvalhodev/saporediluce architecture

> Architecture diagram of the GitHub repository marcoscarvalhodev/saporediluce, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marcoscarvalhodev/saporediluce
- Repository: https://github.com/marcoscarvalhodev/saporediluce

## Overview

##### Project type and purpose
- This is a client-only React + TypeScript web application, built with Vite, that provides an interactive 3D restaurant simulation in the browser.
- It uses a Canvas/WebGL scene (via libraries like React-Three-Fiber), React Context for state management, and static assets (3D models, audio) served from the public folder.

##### File structure
- Top level:
- public/ — all .glb models, textures, audio files, environment HDR
- src/ — React application source, subdivided by feature (AccessButtons, AudioManagement, CameraManagement, ModelsManagement, RestaurantMenu, RestaurantOverlays, RestaurantWaitress, ReviewsCustomers, TableCustomers)
- src/context/ — global state providers (AnimationsContext, AudioChoiceContext, ButtonsContext, etc.)
- src/helpers/ — pure functions and reducers (buttonsReducer)
- CanvasContainer.tsx, main.tsx — bootstrap and root scene container
- Configs: vite.config.ts, tsconfig*.json, eslint.config.js

##### README for additional insights
- The README is the standard React+TS+Vite template description (HMR, ESLint recommendations), confirming the tech stack but not prescribing architecture.

- Browser / User Interface
- Vite Dev/Prod Server (static hosting)
- React Application
– Root Mount (index.html → main.tsx)
– CanvasContainer (sets up WebGL canvas and providers)
– Context Providers (AnimationsContext, AudioChoiceContext, ButtonsContext, CameraMovementContext, FoodContext, HumansContext, OverlaysContext)
– Feature Components (AccessButtons, CameraManagement, ModelsManagement, RestaurantMenu, RestaurantOverlays, RestaurantWaitress, ReviewsCustomers, TableCustomers)
- Asset Loader / Static Assets (public folder: .glb, audio, textures)
- External Libraries (React, React-Three-Fiber, Drei/GLTFLoader, Web Audio API, ESLint)

– Browser GETs index.html from Vite → main.tsx mounts React tree
– CanvasContainer initializes WebGL scene → wraps Context Providers
– Context Providers supply global state → consumed by Feature Components
– Feature Components dispatch actions (e.g. button click → ButtonsContext → triggers OverlaysContext + AudioChoiceContext + AnimationsContext)
– ModelsManagement uses GLTFLoader to pull .glb files from public → adds meshes to scene graph
– AudioManagement plays sounds via Web Audio API based on AudioChoiceContext
– CameraManagement updates camera parameters in Three.js scene

c. Architectural patterns & principles:
– Component-based UI (React)
– Unidirectional data flow via React Context (Flux-like)
– Scene Graph pattern for 3D (WebGL/Three.js)
– Separation of concerns: static asset hosting, state management, presentation, side effects

d. Key technologies & frameworks:
– React 18, TypeScript, Vite (bundler/dev server)
– React-Three-Fiber (Three.js in React) & @react-three/drei (GLTFLoader)
– Web Audio API for sound effects
– ESLint for code quality

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser and Server
    Browser["Browser / User Interface"]:::ui
    Browser-->|"GET index.html"| Vite["Vite Dev/Prod Server (Vite)"]:::server

    %% Static Assets
    Assets["Static Assets (public/)"]:::assets
    click Assets "https://github.com/marcoscarvalhodev/saporediluce/tree/master/public/"

    Vite-->|"serves static files & index.html"| ReactRoot["Root Mount<br>(index.html → main.tsx)"]:::app
    click ReactRoot "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/main.tsx"
    click ReactRoot "https://github.com/marcoscarvalhodev/saporediluce/blob/master/index.html"

    %% React Application
    subgraph "React Application"
        Canvas["CanvasContainer"]:::engine
        click Canvas "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/CanvasContainer.tsx"

        subgraph "Context Providers" 
            Anim["AnimationsContext"]:::context
            click Anim "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/context/AnimationsContext.tsx"
            AudioC["AudioChoiceContext"]:::context
            click AudioC "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/context/AudioChoiceContext.tsx"
            ButtonsC["ButtonsContext"]:::context
            click ButtonsC "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/context/ButtonsContext.tsx"
            CameraC["CameraMovementContext"]:::context
            click CameraC "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/context/CameraMovementContext.tsx"
            FoodC["FoodContext"]:::context
            click FoodC "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/context/FoodContext.tsx"
            HumansC["HumansContext"]:::context
            click HumansC "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/context/HumansContext.tsx"
            OverlaysC["OverlaysContext"]:::context
            click OverlaysC "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/context/OverlaysContext.tsx"
            CreateCtx["CreateContexts"]:::context
            click CreateCtx "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/context/CreateContexts.tsx"
            UseCtx["UseContexts"]:::context
            click UseCtx "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/context/UseContexts.tsx"
        end

        subgraph "Feature Components"
            AccessBtn["AccessButtons"]:::ui
            click AccessBtn "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/AccessButtons/AccessButtons.tsx"
            ButtonReusable["ButtonReusable"]:::ui
            click ButtonReusable "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/AccessButtons/ButtonReusable.tsx"

            AudioChoice["AudioChoice"]:::ui
            click AudioChoice "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/AudioManagement/AudioChoice.tsx"
            AudioEffects["AudioEffects"]:::ui
            click AudioEffects "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/AudioManagement/AudioEffects.tsx"

            MoveCam["MoveCameraOrbit"]:::ui
            click MoveCam "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/CameraManagement/MoveCameraOrbit.tsx"

            Restaurant["Restaurant (Models)"]:::ui
            click Restaurant "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/ModelsManagement/Restaurant.tsx"
            RestaurantDishes["RestaurantDishes"]:::ui
            click RestaurantDishes "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/ModelsManagement/RestaurantDishes.tsx"

            Menu["RestaurantMenu"]:::ui
            click Menu "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/RestaurantMenu/RestaurantMenu.tsx"
            MenuOpts["RestaurantMenuOptions"]:::ui
            click MenuOpts "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/RestaurantMenu/RestaurantMenuOptions.tsx"

            Overlays["RestaurantOverlays"]:::ui
            click Overlays "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/RestaurantOverlays/MenuOverlay.tsx"
            click Overlays "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/RestaurantOverlays/EatingOverlay.tsx"
            click Overlays "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/RestaurantOverlays/FoodReadyOverlay.tsx"
            click Overlays "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/RestaurantOverlays/WaitressActionsOverlay.tsx"

            Waitress["RestaurantWaitress"]:::ui
            click Waitress "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/RestaurantWaitress/Waitress.tsx"
            WaitressDlg["WaitressDialogue"]:::ui
            click WaitressDlg "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/RestaurantWaitress/WaitressDialogue.tsx"
            Notepad["NotepadPen"]:::ui
            click Notepad "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/RestaurantWaitress/NotepadPen.tsx"

            Reviews["ReviewsCustomers"]:::ui
            click Reviews "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/ReviewsCustomers/ReviewsCustomers.tsx"
            Stars["StarsComponent"]:::ui
            click Stars "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/ReviewsCustomers/StarsComponent.tsx"
            TypeTxt["TypewriterText"]:::ui
            click TypeTxt "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/ReviewsCustomers/TypewriterText.tsx"

            TableMain["TableCustomersMain"]:::ui
            click TableMain "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/TableCustomers/TableCustomersMain.tsx"
            Table1["TableCustomers1"]:::ui
            click Table1 "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/TableCustomers/TableCustomers1.tsx"
        end
    end

    %% Helpers and Config
    Helpers["buttonsReducer.tsx"]:::helper
    click Helpers "https://github.com/marcoscarvalhodev/saporediluce/blob/master/src/helpers/buttonsReducer.tsx"
    Configs["Configuration & Tooling"]:::config
    click Configs "https://github.com/marcoscarvalhodev/saporediluce/blob/master/vite.config.ts"
    click Configs "https://github.com/marcoscarvalhodev/saporediluce/blob/master/tsconfig.json"
    click Configs "https://github.com/marcoscarvalhodev/saporediluce/blob/master/eslint.config.js"

    %% Connections
    ReactRoot --> Canvas
    Canvas --> Anim
    Canvas --> AudioC
    Canvas --> ButtonsC
    Canvas --> CameraC
    Canvas --> FoodC
    Canvas --> HumansC
    Canvas --> OverlaysC
    Canvas --> CreateCtx
    Canvas --> UseCtx

    Anim -->|consumed by| AccessBtn
    AudioC -->|state for| AudioChoice
    ButtonsC -->|dispatch actions to| OverlaysC
    CameraC -->|provides| MoveCam
    FoodC -->|provides| Menu
    HumansC -->|provides| Reviews
    OverlaysC -->|drives| Overlays
    CreateCtx -->|initializes| Canvas
    UseCtx -->|hooks used by| TableMain

    AccessBtn -->|reusable| ButtonReusable
    AudioChoice -->|triggers| AudioEffects
    Restaurant -->|loads via GLTFLoader| Assets
    RestaurantDishes -->|loads via GLTFLoader| Assets
    AudioEffects -->|plays via WebAudioAPI| AudioC
    MoveCam -->|updates| CameraC

    Configs --> Vite
    Configs --> ReactRoot

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef server fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef assets fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef app fill:#d4edda,stroke:#155724,color:#155724
    classDef engine fill:#fff3cd,stroke:#856404,color:#856404
    classDef context fill:#d1ecf1,stroke:#0c5460,color:#0c5460
    classDef helper fill:#f5f5f5,stroke:#333, color:#333
    classDef config fill:#f5f5f5,stroke:#333, color:#333
```
