# puente123/3d-lab-manager architecture

> Architecture diagram of the GitHub repository puente123/3d-lab-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/puente123/3d-lab-manager
- Repository: https://github.com/puente123/3d-lab-manager

## Overview

1. **Repository shape**
   - This repo is primarily a **React single-page frontend** for a “3D Lab Manager” application.
   - The visible tree contains **one substantial application surface**: `frontend/`.
   - A `backend/` directory exists, but no backend implementation is visible in the provided tree; the frontend architecture strongly suggests the app talks to **Supabase-backed services** instead of a custom server in this repo.

2. **Application shell**
   - The frontend is built with **Vite + React**.
   - `frontend/src/main.jsx` bootstraps the app, and `App.jsx` likely defines the top-level route/layout composition.
   - Global styling is split between `src/index.css`, `src/styles/globals.css`, and component-local CSS such as `App.css`.

3. **Navigation and page boundaries**
   - User-facing pages live in `src/pages/`:
     - Public/auth: `Home`, `Auth`, `ResetPassword`
     - Inventory/navigation: `Items`, `ItemDetail`
     - Spatial/lab views: `Map3d`, `Map3dIndex`
   - Admin pages are isolated under `src/pages/admin/`:
     - `IssuesAdmin`, `ItemsAdmin`, `LabsAdmin`, `ModelsAdmin`, `ReportsAdmin`, `SettingsAdmin`, `UsersAdmin`
   - This separation indicates a clear boundary between **general user workflows** and **privileged management workflows**.

4. **Authentication and authorization flow**
   - `src/contexts/AuthContext.jsx` centralizes auth state and likely exposes the current user/session to the rest of the app.
   - Route protection is handled by:
     - `src/components/ProtectedRoute.jsx` for authenticated user-only routes
     - `src/components/admin/AdminProtectedRoute.jsx` for admin-only access
   - This means the routing layer depends on auth context before rendering sensitive pages or admin tools.

5. **Domain service layer**
   - `src/lib/` is the main data-access boundary.
   - Each file maps to a domain area or external capability:
     - `supabaseItems.js`
     - `supabaseLabs.js`
     - `supabaseIssues.js`
     - `supabaseCheckout.js`
     - `supabaseUsers.js`
     - `supabaseStorage.js`
     - `supabase.js` for the shared client
     - `api.js` for any non-Supabase HTTP calls
   - `permissions.js` isolates role/ability checks.
   - This layering keeps UI components and pages from talking directly to the data backend.

6. **Core data model implied by the code**
   - The named modules point to the main entities in the system:
     - **items/equipment**
     - **labs**
     - **issues**
     - **checkout/loans**
     - **users**
     - **stored files/images/models**
   - The app is therefore not just a catalog; it supports **inventory management**, **issue reporting**, and **asset lifecycle operations** around lab equipment and spaces.

7. **UI component structure**
   - Shared presentational components live in `src/components/`:
     - `ItemCard`, `LabCard`, `EquipmentDetails`
     - `SearchBar`, `EmptyState`, `LoadingSkeleton`
     - `IssueModal`, `TopNav`, `Footer`, `SkipLink`
   - The component set suggests a user flow of:
     - browse/search lists
     - open a detail page
     - inspect equipment/lab metadata
     - create/report issues via modal interaction
   - Admin-specific shared UI is kept separate under `src/components/admin/`.

8. **3D / spatial lab view**
   - `Map3d.jsx` and `Map3dIndex.jsx` indicate a dedicated **3D or spatial representation** of labs/equipment.
   - `src/config/labs.js` likely provides the lab layout/configuration data used by these pages.
   - `src/public/images/labs` and related image assets suggest the spatial view may combine configuration with static visual assets rather than purely generated 3D geometry.

9. **Mocking and test architecture**
   - The project uses **Vitest** for unit/component tests and **MSW** for network mocking.
   - Mock infrastructure lives in `src/mocks/` with separate datasets/handlers for general and admin scenarios.
   - `src/tests/setup.js` and `src/tests/mocks/supabase.js` indicate tests are designed to simulate the Supabase boundary cleanly.
   - Existing tests cover auth, permissions, protected routes, search, and some supabase item behavior, showing that the repo treats **access control and data fetching as key system concerns**.

10. **Deployment/runtime boundary**
   - `frontend/Dockerfile` and `frontend/nginx.conf` show the frontend is packaged as a **static build served by Nginx**.
   - This is consistent with a SPA architecture where runtime behavior is mostly in the browser and data access happens through external services.

11. **Asset and content handling**
   - `frontend/public/images/items` and `frontend/public/images/labs` hold static imagery for the catalog and lab views.
   - `supabaseStorage.js` suggests user-uploaded or backend-managed files are also part of the architecture, not just static assets.

12. **Architectural summary for a diagram**
   - The clearest diagram is:
     - **Browser/UI layer**: pages + reusable components
     - **State/auth layer**: `AuthContext`, route guards, permissions
     - **Domain service layer**: `src/lib/*` wrappers
     - **External platform layer**: Supabase auth/database/storage
     - **Static asset layer**: images, config, mock fixtures
   - Admin and user flows share the same core data services but diverge in route protection and page composition.

Main entry points: [`frontend/src/App.jsx`](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/App.jsx) (App shell), [`frontend/src/lib/supabase.js`](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/lib/supabase.js) (Data services), [`frontend/src/tests/setup.js`](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/tests/setup.js) (Tests), [`frontend/src/components/ItemCard.jsx`](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/components/ItemCard.jsx) (Shared UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend app"]
  node_main(("Entry<br/>bootstrap<br/>[main.jsx]"))
  node_app["App shell<br/>layout/router<br/>[App.jsx]"]
  node_authctx{{"Auth state<br/>context<br/>[AuthContext.jsx]"}}
  node_protected["Route guards<br/>access control<br/>[ProtectedRoute.jsx]"]
  node_adminprotected["Admin guards<br/>access control"]
  node_pages_public["Public pages<br/>[Home.jsx]"]
  node_pages_detail["Item views<br/>pages<br/>[Items.jsx]"]
  node_pages_spatial["Spatial views<br/>pages<br/>[Map3d.jsx]"]
  node_pages_admin["Admin pages<br/>[IssuesAdmin.jsx]"]
  node_ui_shared["Shared UI<br/>components<br/>[ItemCard.jsx]"]
  node_ui_admin["Admin UI<br/>components<br/>[AdminLayout.jsx]"]
  node_services[("Data services<br/>domain services<br/>[supabase.js]")]
  node_tests["Tests<br/>verification<br/>[setup.js]"]
end

subgraph group_platform["Platform"]
  node_supabase[("Supabase<br/>external platform")]
  node_deploy["Nginx SPA<br/>runtime<br/>[nginx.conf]"]
end

subgraph group_assets["Assets & mocks"]
  node_assets_images["Images<br/>static assets"]
  node_labs_config["Lab config<br/>configuration<br/>[labs.js]"]
  node_mocks["Mocks<br/>test data<br/>[handlers.js]"]
end

node_main -->|"mounts"| node_app
node_app -->|"reads session"| node_authctx
node_app -->|"guards routes"| node_protected
node_app -->|"guards admin"| node_adminprotected
node_app -->|"renders"| node_pages_public
node_app -->|"renders"| node_pages_detail
node_app -->|"renders"| node_pages_spatial
node_app -->|"renders"| node_pages_admin
node_pages_public -->|"uses"| node_ui_shared
node_pages_detail -->|"uses"| node_ui_shared
node_pages_spatial -->|"uses"| node_ui_shared
node_pages_admin -->|"uses"| node_ui_admin
node_ui_shared -->|"fetches data"| node_services
node_ui_admin -->|"fetches data"| node_services
node_services -->|"calls"| node_supabase
node_services -->|"references"| node_assets_images
node_pages_spatial -->|"uses layout"| node_labs_config
node_mocks -.->|"simulates"| node_services
node_tests -.->|"verifies"| node_authctx
node_tests -.->|"verifies"| node_protected
node_tests -.->|"verifies"| node_adminprotected
node_tests -.->|"verifies"| node_services
node_deploy -->|"serves"| node_main

click node_main "https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/main.jsx"
click node_app "https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/App.jsx"
click node_authctx "https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/contexts/AuthContext.jsx"
click node_protected "https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/components/ProtectedRoute.jsx"
click node_adminprotected "https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/components/admin/AdminProtectedRoute.jsx"
click node_pages_public "https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/pages/Home.jsx"
click node_pages_detail "https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/pages/Items.jsx"
click node_pages_spatial "https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/pages/Map3d.jsx"
click node_pages_admin "https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/pages/admin/IssuesAdmin.jsx"
click node_ui_shared "https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/components/ItemCard.jsx"
click node_ui_admin "https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/components/admin/AdminLayout.jsx"
click node_services "https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/lib/supabase.js"
click node_deploy "https://github.com/puente123/3d-lab-manager/blob/main/frontend/nginx.conf"
click node_assets_images "https://github.com/puente123/3d-lab-manager/tree/main/frontend/public/images/items"
click node_labs_config "https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/config/labs.js"
click node_mocks "https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/mocks/handlers.js"
click node_tests "https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/tests/setup.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_app,node_authctx,node_protected,node_adminprotected,node_pages_public,node_pages_detail,node_pages_spatial,node_pages_admin,node_ui_shared,node_ui_admin,node_services,node_tests toneBlue
class node_supabase,node_deploy toneAmber
class node_assets_images,node_labs_config,node_mocks toneMint
```

## Components

### Frontend app

Vite + React SPA and its internal app layers.

- [Entry](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/main.jsx): bootstrap · Vite entry that mounts the React app. · `frontend/src/main.jsx`
- [App shell](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/App.jsx): layout/router · Top-level composition for routes, layout, and global app wiring. · `frontend/src/App.jsx`
- [Auth state](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/contexts/AuthContext.jsx): context · Central session and user state shared across the UI. · `frontend/src/contexts/AuthContext.jsx`
- [Route guards](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/components/ProtectedRoute.jsx): access control · Authenticated user route protection. · `frontend/src/components/ProtectedRoute.jsx`
- [Admin guards](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/components/admin/AdminProtectedRoute.jsx): access control · Admin-only route protection. · `frontend/src/components/admin/AdminProtectedRoute.jsx`
- [Public pages](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/pages/Home.jsx): pages · Home, auth, reset-password, and inventory browsing pages. · `frontend/src/pages/Home.jsx`
- [Item views](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/pages/Items.jsx): pages · Item listing and detail workflows. · `frontend/src/pages/Items.jsx`
- [Spatial views](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/pages/Map3d.jsx): pages · 3D or spatial lab exploration pages. · `frontend/src/pages/Map3d.jsx`
- [Admin pages](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/pages/admin/IssuesAdmin.jsx): pages · Privileged management screens for issues, items, labs, models, reports, settings, and users. · `frontend/src/pages/admin/IssuesAdmin.jsx`
- [Shared UI](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/components/ItemCard.jsx): components · Reusable presentational components for browsing, details, and feedback. · `frontend/src/components/ItemCard.jsx`
- [Admin UI](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/components/admin/AdminLayout.jsx): components · Admin-specific layout and shared admin interface pieces. · `frontend/src/components/admin/AdminLayout.jsx`
- [Data services](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/lib/supabase.js): domain services · Client-side wrappers around Supabase, storage, permissions, and auxiliary APIs. · `frontend/src/lib/supabase.js`
- [Tests](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/tests/setup.js): verification · Vitest and integration setup covering auth, permissions, routing, and data access. · `frontend/src/tests/setup.js`

### Platform

External services and deployment/runtime boundary.

- **Supabase**: external platform · Auth, database, and storage backend consumed by the frontend.
- [Nginx SPA](https://github.com/puente123/3d-lab-manager/blob/main/frontend/nginx.conf): runtime · Static frontend build served through Nginx in production. · `frontend/nginx.conf`

### Assets & mocks

Static content, config, and test doubles used by the app.

- [Images](https://github.com/puente123/3d-lab-manager/tree/main/frontend/public/images/items): static assets · Catalog and lab imagery used across the UI. · `frontend/public/images/items`
- [Lab config](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/config/labs.js): configuration · Spatial/lab layout data used by map views. · `frontend/src/config/labs.js`
- [Mocks](https://github.com/puente123/3d-lab-manager/blob/main/frontend/src/mocks/handlers.js): test data · MSW handlers and fixtures for browser and test scenarios. · `frontend/src/mocks/handlers.js`

## Connections

- Entry → App shell: mounts · Bootstraps the root React application.
- App shell → Auth state: reads session · App composition depends on shared auth state.
- App shell → Route guards: guards routes · Authenticated routes are wrapped by the general guard.
- App shell → Admin guards: guards admin · Admin routes are wrapped by the admin guard.
- App shell → Public pages: renders · Public and auth-related screens are composed at the top level.
- App shell → Item views: renders · Item browsing and detail pages are part of the main app surface.
- App shell → Spatial views: renders · Spatial and 3D lab pages are part of the main app surface.
- App shell → Admin pages: renders · Admin screens are routed from the app shell.
- Public pages → Shared UI: uses · Public screens reuse common UI primitives.
- Item views → Shared UI: uses · Listing and detail pages use shared cards, search, empty state, and loading UI.
- Spatial views → Shared UI: uses · Spatial views reuse shared navigation and feedback components.
- Admin pages → Admin UI: uses · Admin screens rely on admin-specific layout and helpers.
- Shared UI → Data services: fetches data · UI components and pages consume domain service wrappers.
- Admin UI → Data services: fetches data · Admin tools use the same service layer for privileged operations.
- Data services → Supabase: calls · Primary persistence and auth boundary is Supabase.
- Data services → Images: references · UI data flows are paired with catalog and lab imagery.
- Spatial views → Lab config: uses layout · 3D or map pages use lab configuration data.
- Mocks → Data services: simulates · MSW fixtures emulate the service boundary in development and tests.
- Tests → Auth state: verifies · Tests cover auth and context behavior.
- Tests → Route guards: verifies · Tests cover authenticated route protection.
- Tests → Admin guards: verifies · Tests cover admin-only access control.
- Tests → Data services: verifies · Tests cover permissions and Supabase item behavior.
- Nginx SPA → Entry: serves · Production runtime serves the built SPA.