How puente123/3d-lab-manager works
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: App.jsx App shell · supabase.js Data services · setup.js Tests · ItemCard.jsx Shared UI
Components 18
Frontend app
Vite + React SPA and its internal app layers.
- Entry · Vite entry that mounts the React app.
frontend/src/main.jsx - App shell · Top-level composition for routes, layout, and global app wiring.
frontend/src/App.jsx - Auth state · Central session and user state shared across the UI.
frontend/src/contexts/AuthContext.jsx - Route guards · Authenticated user route protection.
frontend/src/components/ProtectedRoute.jsx - Admin guards · Admin-only route protection.
frontend/src/components/admin/AdminProtectedRoute.jsx - Public pages · Home, auth, reset-password, and inventory browsing pages.
frontend/src/pages/Home.jsx - Item views · Item listing and detail workflows.
frontend/src/pages/Items.jsx - Spatial views · 3D or spatial lab exploration pages.
frontend/src/pages/Map3d.jsx - Admin pages · Privileged management screens for issues, items, labs, models, reports, settings, and users.
frontend/src/pages/admin/IssuesAdmin.jsx - Shared UI · Reusable presentational components for browsing, details, and feedback.
frontend/src/components/ItemCard.jsx - Admin UI · Admin-specific layout and shared admin interface pieces.
frontend/src/components/admin/AdminLayout.jsx - Data services · Client-side wrappers around Supabase, storage, permissions, and auxiliary APIs.
frontend/src/lib/supabase.js - Tests · Vitest and integration setup covering auth, permissions, routing, and data access.
frontend/src/tests/setup.js
Platform
External services and deployment/runtime boundary.
- Supabase · Auth, database, and storage backend consumed by the frontend.
- Nginx SPA · Static frontend build served through Nginx in production.
frontend/nginx.conf
Assets & mocks
Static content, config, and test doubles used by the app.
- Images · Catalog and lab imagery used across the UI.
frontend/public/images/items - Lab config · Spatial/lab layout data used by map views.
frontend/src/config/labs.js - Mocks · MSW handlers and fixtures for browser and test scenarios.
frontend/src/mocks/handlers.js
Connections 23
- 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.