# justinscitech/sceneit architecture

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

- Interactive diagram: https://gitdiagram.com/justinscitech/sceneit
- Repository: https://github.com/justinscitech/sceneit

## Overview

##### Project type and purpose
- This is a full-stack, server-rendered e-commerce web application built with Next.js (using the new /app directory), React, Tailwind CSS, and various UI components.
- It integrates with Shopify, exposes REST/HTTP APIs for 3D-model generation and image analysis, and leverages Python scripts for AI/ML tasks (e.g., `generate_3d_model.py`, `benchmark_triposr.py`).

##### File structure
- Top-level “app” directory: Next.js app routes, React pages, layouts, error handling.
- app/api: serverless API endpoints written in TypeScript (3D models, image analysis, product sync).
- pages/api/vapi: legacy Next.js API routes for voice-AI assistant (OpenAI).
- components, components/ui: shared React components, UI primitives, layout, cart, product viewers.
- lib/shopify, lib/utils: Shopify integration, utilities, context providers.
- Python scripts at root: standalone microservices for 3D model generation and benchmarking.
- public/3D: static 3D assets (GLB files).
- server/tmp: temporary storage for vendor product data.
- configuration files: next.config.mjs, tailwind.config.js, tsconfig.json, package.json.

##### README for additional insights
- The README (“Scene it will revolutionize … voice ai sales guides”) indicates a voice-AI assistant layer on top of e-commerce product browsing and 3D visualization.

##### Components and relationships
a. Main components
- Client (Browser/Mobile): Next.js-driven React UI, 3D viewer, voice UI
- Next.js Server (Node.js): SSR/ISR, API routes under /app/api and /pages/api/vapi
- Python AI/ML Service: separate microservice(s) running Python scripts for 3D-model generation and image analysis
- Shopify API: external e-commerce backend for product catalog
- Data Store / File Store: public/3D for static assets, server/tmp for intermediate JSON, possible cloud storage or CDN
- Voice-AI Provider: external OpenAI or custom voice assistant API
b. Relationships and interactions
- Browser → Next.js Server: HTTP(S) requests for pages, SSR data-fetching, client-side navigation
- Next.js API routes ←→ Shopify API: sync products, fetch catalog data
- Next.js API routes → Python AI Service: REST or gRPC calls to trigger model generation or analysis
- Python AI Service → File Store/CDN: persists generated 3D models under public/3D or server/tmp
- Browser → Voice-AI Provider: via Next.js /pages/api/vapi routes for creating assistant sessions and webhooks
c. Architectural patterns and design principles
- Jamstack/Serverless Functions for backend logic (Next.js API Routes)
- Microservices for heavy AI tasks (Python scripts decoupled from Node.js)
- Component-based UI with shared “components/ui” primitives for consistency
- Context Providers for global state (Cart, Vendor)
- Static asset hosting plus SSR for SEO and performance
d. Key technologies and frameworks
- Next.js 13 with the /app router
- React + TypeScript
- Tailwind CSS
- Shopfiy Storefront API
- Python (TensorFlow/PyTorch or custom AI libs)
- OpenAI or custom voice-AI API
- CDN or cloud file storage for 3D assets

##### Elements
- from Browser to Next.js SSR (page requests)
- SSR to API Routes (data fetching)
- API Routes to Python service and to Shopify
- Python service to File Storage
- Browser direct fetches for static assets
- Browser to Voice-AI via Next.js vapi routes

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Subgraph Frontend
    subgraph "Frontend Layer" 
        direction TB
        Layout["Layout (app/layout.tsx)"]:::frontend
        Page["Home Page (app/page.tsx)"]:::frontend
        Header["Header (components/layout/header)"]:::frontend
        Footer["Footer (components/layout/footer)"]:::frontend
        3DViewer["3D Viewer (components/product/3d-viewer.tsx)"]:::frontend
        VAPIChat["Voice UI Chat (components/vapi/vapi-chat.tsx)"]:::frontend
        DesktopGallery["Desktop Gallery (app/product/[handle]/components/desktop-gallery.tsx)"]:::frontend
        MobileGallery["Mobile Gallery (app/product/[handle]/components/mobile-gallery-slider.tsx)"]:::frontend
    end

    %% Subgraph Next.js Server
    subgraph "Next.js Server (SSR & API)" 
        direction TB
        SSRShopLayout["Shop Layout (app/shop/layout.tsx)"]:::server
        SSRShopPage["Shop Page (app/shop/page.tsx)"]:::server
        ErrorHandler["Error/NotFound (app/error.tsx & app/not-found.tsx)"]:::server
        API3DModels["3D Models API (app/api/3d-models/route.ts)"]:::server
        APIAnalyzeImage["Analyze Image API (app/api/analyze-image/route.ts)"]:::server
        APIGenerate3D["Generate 3D Model API (app/api/generate-3d-model/route.ts)"]:::server
        APISyncProduct["Sync Product API (app/api/sync-product/route.ts)"]:::server
        VAPICreate["Create Assistant (pages/api/vapi/create-assistant.ts)"]:::server
        VAPIWebhook["Voice Webhook (pages/api/vapi/webhook.ts)"]:::server
    end

    %% Subgraph Python AI/ML 
    subgraph "Python AI/ML Service" 
        direction TB
        Gen3D["generate_3d_model.py"]:::python
        Bench["benchmark_triposr.py"]:::python
        Test1["test_triposr.py"]:::python
        Test2["test_triposr_direct.py"]:::python
    end

    %% Subgraph Shopify Integration
    subgraph "Shopify Integration Library" 
        direction TB
        ShopifyIndex["index.ts"]:::server
        ShopifyCore["shopify.ts"]:::server
        ShopifyConstants["constants.ts"]:::server
        ShopifyParseDomain["parse-shopify-domain.ts"]:::server
        ShopifyStoreName["store-name.ts"]:::server
        ShopifyTypes["types.ts"]:::server
        ShopifyUtils["utils.ts"]:::server
    end

    %% Subgraph Utilities & Context
    subgraph "Utilities & Context Providers" 
        direction TB
        Actions["actions.ts"]:::server
        UtilsLib["utils.ts & utils/*"]:::server
        ContextVendor["vendor-context.tsx"]:::server
        HookWebsocket["use-websocket.ts"]:::server
        CartContext["cart-context.tsx"]:::server
    end

    %% Subgraph Data Stores
    subgraph "Data Stores / File Storage" 
        direction TB
        Public3D["3D Assets (public/3D/*.glb)"]:::datastore
        VendorTmp["Vendor Temp JSON (server/tmp/vendor-products.json)"]:::datastore
    end

    %% External Services
    ShopifyAPI["Shopify Storefront API"]:::external
    VoiceAI["Voice-AI Provider"]:::external

    %% Connections
    %% Frontend --> SSR
    Layout -->|renders| SSRShopLayout
    Page -->|renders| SSRShopPage

    %% Frontend --> APIs
    3DViewer -->|fetch model via| API3DModels
    3DViewer -->|trigger generate| APIGenerate3D
    3DViewer -->|analyze image via| APIAnalyzeImage
    VAPIChat -->|calls| VAPICreate
    VAPIChat -->|receives webhook| VAPIWebhook

    %% SSR/API --> Shopify & Python
    API3DModels -->|store/fetch| Public3D
    APIGenerate3D -->|requests| Gen3D
    APIAnalyzeImage -->|requests| Gen3D
    APISyncProduct -->|sync with| ShopifyAPI
    SSRShopPage -->|uses| ShopifyIndex

    %% Python Service --> Data Stores
    Gen3D -->|writes| Public3D
    Gen3D -->|writes| VendorTmp

    %% Frontend direct static fetch
    Page -->|static assets| Public3D

    %% Voice AI external
    VAPICreate -->|proxy to| VoiceAI
    VAPIWebhook -->|webhook from| VoiceAI

    %% Class Definitions
    classDef frontend fill:#BBDEFB,stroke:#333
    classDef server fill:#90CAF9,stroke:#333
    classDef python fill:#A5D6A7,stroke:#333
    classDef external fill:#FFF59D,stroke:#333
    classDef datastore fill:#BCAAA4,stroke:#333,stroke-dasharray: 5 5

    %% Click Events Frontend
    click Layout "https://github.com/justinscitech/sceneit/blob/main/app/layout.tsx"
    click Page "https://github.com/justinscitech/sceneit/blob/main/app/page.tsx"
    click Header "https://github.com/justinscitech/sceneit/tree/main/components/layout/header"
    click Footer "https://github.com/justinscitech/sceneit/tree/main/components/layout/footer"
    click 3DViewer "https://github.com/justinscitech/sceneit/blob/main/components/product/3d-viewer.tsx"
    click VAPIChat "https://github.com/justinscitech/sceneit/blob/main/components/vapi/vapi-chat.tsx"
    click DesktopGallery "https://github.com/justinscitech/sceneit/blob/main/app/product/[handle]/components/desktop-gallery.tsx"
    click MobileGallery "https://github.com/justinscitech/sceneit/blob/main/app/product/[handle]/components/mobile-gallery-slider.tsx"

    %% Click Events Next.js Server
    click SSRShopLayout "https://github.com/justinscitech/sceneit/blob/main/app/shop/layout.tsx"
    click SSRShopPage "https://github.com/justinscitech/sceneit/blob/main/app/shop/page.tsx"
    click ErrorHandler "https://github.com/justinscitech/sceneit/blob/main/app/error.tsx"
    click API3DModels "https://github.com/justinscitech/sceneit/blob/main/app/api/3d-models/route.ts"
    click APIAnalyzeImage "https://github.com/justinscitech/sceneit/blob/main/app/api/analyze-image/route.ts"
    click APIGenerate3D "https://github.com/justinscitech/sceneit/blob/main/app/api/generate-3d-model/route.ts"
    click APISyncProduct "https://github.com/justinscitech/sceneit/blob/main/app/api/sync-product/route.ts"
    click VAPICreate "https://github.com/justinscitech/sceneit/blob/main/pages/api/vapi/create-assistant.ts"
    click VAPIWebhook "https://github.com/justinscitech/sceneit/blob/main/pages/api/vapi/webhook.ts"

    %% Click Events Python Service
    click Gen3D "https://github.com/justinscitech/sceneit/blob/main/generate_3d_model.py"
    click Bench "https://github.com/justinscitech/sceneit/blob/main/benchmark_triposr.py"
    click Test1 "https://github.com/justinscitech/sceneit/blob/main/test_triposr.py"
    click Test2 "https://github.com/justinscitech/sceneit/blob/main/test_triposr_direct.py"

    %% Click Events Shopify Integration
    click ShopifyIndex "https://github.com/justinscitech/sceneit/blob/main/lib/shopify/index.ts"
    click ShopifyCore "https://github.com/justinscitech/sceneit/blob/main/lib/shopify/shopify.ts"
    click ShopifyConstants "https://github.com/justinscitech/sceneit/blob/main/lib/shopify/constants.ts"
    click ShopifyParseDomain "https://github.com/justinscitech/sceneit/blob/main/lib/shopify/parse-shopify-domain.ts"
    click ShopifyStoreName "https://github.com/justinscitech/sceneit/blob/main/lib/shopify/store-name.ts"
    click ShopifyTypes "https://github.com/justinscitech/sceneit/blob/main/lib/shopify/types.ts"
    click ShopifyUtils "https://github.com/justinscitech/sceneit/blob/main/lib/shopify/utils.ts"

    %% Click Events Utilities & Context
    click Actions "https://github.com/justinscitech/sceneit/blob/main/lib/actions.ts"
    click UtilsLib "https://github.com/justinscitech/sceneit/blob/main/lib/utils.ts"
    click ContextVendor "https://github.com/justinscitech/sceneit/blob/main/lib/context/vendor-context.tsx"
    click HookWebsocket "https://github.com/justinscitech/sceneit/blob/main/hooks/use-websocket.ts"
    click CartContext "https://github.com/justinscitech/sceneit/blob/main/components/cart/cart-context.tsx"
    
    %% Click Events Data Stores
    click Public3D "https://github.com/justinscitech/sceneit/tree/main/public/3D"
    click VendorTmp "https://github.com/justinscitech/sceneit/blob/main/server/tmp/vendor-products.json"
```
