Project Structure

Overview of the StorySplat monorepo organization.

Repository Layout

gaussian-splatting-viewer/
├── src/                      # Main React application
│   ├── components/           # React components
│   │   ├── Scene/           # 3D scene components
│   │   └── ...              # UI components
│   ├── hooks/               # Custom React hooks
│   ├── contexts/            # React contexts (Auth, Stripe, etc.)
│   ├── pages/               # Route-level components
│   ├── tools/               # Export and generation tools
│   │   └── html-generation/ # HTML export system
│   ├── utils/               # Utility functions
│   └── types/               # TypeScript type definitions
│
├── discover/                 # Next.js viewer/discovery app
│   ├── app/                 # Next.js app router
│   ├── components/          # Discovery-specific components
│   └── lib/                 # Shared utilities
│
├── functions/               # Firebase Cloud Functions
│   └── src/                 # Function implementations
│
├── storysplat-viewer/       # npm package
│   ├── src/                 # Package source
│   │   ├── dynamic-viewer/  # Viewer implementation
│   │   └── types/           # Type definitions
│   └── dist/                # Built package
│
├── splat-tools/             # Desktop app (Electron)
│   ├── src/
│   │   ├── main/           # Electron main process
│   │   ├── renderer/       # React renderer
│   │   └── sharp/          # Python integration
│   └── electron/           # Electron config
│
└── docs/                    # Documentation (MkDocs)
    ├── viewer/             # Viewer docs
    ├── tools/              # Tools docs
    └── advanced/           # Advanced topics

Main Application (src/)

The primary React application for scene creation.

Key Directories

src/
├── components/
│   ├── Scene/
│   │   ├── SceneCanvas.tsx      # BabylonJS canvas
│   │   ├── SplatLoader.tsx      # Splat file loading
│   │   ├── CameraControls.tsx   # Camera modes
│   │   ├── HotspotManager.tsx   # Hotspot system
│   │   └── WaypointEditor.tsx   # Waypoint editing
│   ├── Editor/
│   │   ├── PropertiesPanel.tsx  # Scene properties
│   │   ├── Timeline.tsx         # Animation timeline
│   │   └── AssetBrowser.tsx     # Asset management
│   └── UI/
│       ├── Button.tsx
│       ├── Modal.tsx
│       └── ...
│
├── hooks/
│   ├── useScene.ts              # Scene state management
│   ├── useCamera.ts             # Camera controls
│   ├── useExport.ts             # Export functionality
│   └── useMobile.ts             # Mobile detection
│
├── contexts/
│   ├── AuthContext.tsx          # Firebase auth
│   ├── StripeContext.tsx        # Subscription state
│   └── SceneContext.tsx         # Active scene context
│
├── tools/
│   └── html-generation/
│       ├── GenerateExportedHtml.ts  # Main export
│       ├── template.ts              # HTML template
│       ├── mainScript.ts            # Viewer script
│       └── modules/                 # Feature modules
│           ├── hotspots.ts
│           ├── waypoints.ts
│           └── ...
│
└── types/
    ├── scene.ts                 # Scene types
    ├── camera.ts                # Camera types
    └── export.ts                # Export types

Data Flow

User Interaction
      │
      ▼
React Components ◄──► React Context
      │                    │
      ▼                    ▼
BabylonJS Scene       Firebase (Auth/Store)
      │
      ▼
Export System ──► HTML Output

Discovery App (discover/)

Next.js application for public scene viewing.

discover/
├── app/
│   ├── page.tsx             # Home/discovery page
│   ├── scene/[id]/
│   │   └── page.tsx         # Scene viewer
│   ├── user/[id]/
│   │   └── page.tsx         # User profile
│   └── api/
│       └── ...              # API routes
│
├── components/
│   ├── SceneCard.tsx        # Scene preview card
│   ├── SceneViewer.tsx      # Embedded viewer
│   └── UserAvatar.tsx       # User display
│
└── lib/
    ├── firebase.ts          # Firebase client
    └── utils.ts             # Utilities

StorySplat Viewer Package (storysplat-viewer/)

The npm package for embedding viewers.

storysplat-viewer/
├── src/
│   ├── index.ts             # Package entry
│   ├── dynamic-viewer/
│   │   ├── createViewer.ts  # Main factory
│   │   ├── FrameSequencePlayer.ts  # 4DGS player
│   │   ├── EventEmitter.ts  # Event system
│   │   └── controls/
│   │       ├── OrbitControls.ts
│   │       └── FirstPersonControls.ts
│   └── types/
│       └── index.ts         # Public types
│
├── dist/                    # Built output
│   ├── index.esm.js         # ES modules
│   ├── index.cjs.js         # CommonJS
│   ├── storysplat-viewer.umd.js  # UMD
│   └── index.d.ts           # Types
│
└── EXPORTED_FEATURES_REFERENCE.md  # Feature parity doc

StorySplat Tools (splat-tools/)

Electron desktop application.

splat-tools/
├── src/
│   ├── main/
│   │   ├── index.ts         # Main process entry
│   │   ├── ipc.ts           # IPC handlers
│   │   └── menu.ts          # App menu
│   │
│   ├── renderer/
│   │   ├── App.tsx          # React app
│   │   ├── components/
│   │   │   ├── ConvertTab.tsx
│   │   │   ├── Image2SplatTab.tsx
│   │   │   ├── Video2SplatTab.tsx
│   │   │   └── PreviewTab.tsx
│   │   └── hooks/
│   │       └── useProcessing.ts
│   │
│   └── sharp/               # Python integration
│       ├── runner.ts        # Python process runner
│       ├── venv.ts          # Virtual env management
│       └── scripts/         # Python scripts
│           ├── image2splat.py
│           └── video2splat.py
│
├── electron/
│   ├── main.ts
│   └── preload.ts
│
└── package.json

Firebase Functions (functions/)

Backend serverless functions.

functions/
├── src/
│   ├── index.ts             # Function exports
│   ├── analytics/
│   │   └── trackViews.ts    # View tracking
│   ├── payments/
│   │   ├── webhooks.ts      # Stripe webhooks
│   │   └── subscription.ts  # Sub management
│   ├── social/
│   │   ├── likes.ts         # Like system
│   │   └── comments.ts      # Comment system
│   └── storage/
│       └── onUpload.ts      # File processing
│
└── package.json

Documentation (docs/)

MkDocs documentation site.

docs/
├── mkdocs.yml               # MkDocs config
├── index.md                 # Home page
├── getting-started/
│   ├── quick-start.md
│   └── installation.md
├── viewer/
│   ├── overview.md
│   ├── basic-usage.md
│   ├── 4dgs-playback.md
│   ├── api-reference.md
│   └── events.md
├── tools/
│   ├── overview.md
│   ├── format-conversion.md
│   ├── image-to-splat.md
│   ├── video-to-4dgs.md
│   └── cli-reference.md
├── architecture/
│   ├── project-structure.md
│   └── DUAL_URL_ARCHITECTURE.md
└── advanced/
    ├── hosting-4dgs.md
    └── custom-integrations.md

Build Outputs

# Main app
dist/                        # Vite build output

# Discovery app
discover/.next/              # Next.js build

# Viewer package
storysplat-viewer/dist/      # Package build

# Desktop app
splat-tools/out/             # Electron build
  ├── win-unpacked/
  ├── mac/
  └── linux-unpacked/

# Functions
functions/lib/               # Compiled functions

Configuration Files

Root:
├── package.json             # Root package
├── tsconfig.json            # TypeScript config
├── vite.config.ts           # Vite config
├── .env                     # Environment variables
├── .env.example             # Env template
├── firebase.json            # Firebase config
├── firestore.rules          # Firestore security
├── storage.rules            # Storage security
└── netlify.toml             # Netlify deploy config

Per-package:
├── discover/package.json
├── functions/package.json
├── storysplat-viewer/package.json
└── splat-tools/package.json

Development Workflow

# Root - Main app
npm run dev                  # Start dev server

# Discovery
cd discover && npm run dev   # Next.js dev

# Functions
cd functions && npm run serve  # Local emulator

# Viewer package
cd storysplat-viewer && npm run build  # Build package

# Desktop app
cd splat-tools && npm run dev  # Electron dev

Key Dependencies

Package	Purpose
React	UI framework
BabylonJS	3D rendering (main app)
PlayCanvas	3D rendering (viewer)
Firebase	Auth, database, storage
Stripe	Payments
Electron	Desktop app
Vite	Build tool
Next.js	Discovery app
MkDocs	Documentation