upload-gltf/README.md

# upload-GLTF

A secure web interface for uploading `model.gltf` with its associated `.bin` file and textures with two outputs:

- **Nextcloud Drive** — Archives the original files with automatic versioning (VF/V1/V2...), so artists always have a history of past versions
- **GitHub** — Delivers GLTF assets and compressed textures to the dev team's repository, ready for integration

Built for La Fabrik Durable's internal use, but open-sourced for anyone looking for a similar solution. The app validates the upload locally, stages it server-side, then applies intelligent diffs to avoid unnecessary uploads and commits. The Drive upload serves as the source of truth and version history, while the GitHub upload delivers the prepared assets to developers

## Stack

- [**Next.js 16** (App Router)](https://nextjs.org/docs/app/getting-started/installation) + [React 19](https://react.dev/learn/creating-a-react-app) + [TypeScript](https://www.typescriptlang.org/docs/)
- [**Three.js**](https://threejs.org/docs/#manual/en/introduction/Creating-a-scene) ([React Three Fiber](https://r3f.docs.pmnd.rs/getting-started/introduction) + [Drei](https://drei.docs.pmnd.rs/getting-started/introduction)) for 3D preview
- [**Tailwind CSS**](https://v3.tailwindcss.com/docs/installation) for styling
- [**Octokit**](https://github.com/octokit/rest.js/#readme) for pushing via the GitHub API
- [**Nextcloud WebDAV**](https://docs.nextcloud.com/server/latest/developer_manual/client_apis/WebDAV/index.html) for Drive archiving with automatic versioning
- [**Sharp**](https://sharp.pixelplumbing.com/install/) for server-side texture compression
- [**Coolify** (Docker)](https://coolify.io/docs/applications/build-packs/dockerfile) for hosting

## Usage

### Development

```bash
npm run dev
```
The app runs on `http://localhost:3000` with hot reload. The upload API routes are available under `http://localhost:3000/api/upload/*`

## How it works

1. The user enters their access key
2. They select a folder containing:
   - `model.gltf` (**required**)
   - Any associated binary buffer (`.bin`, for example `model.bin`)
   - Any associated textures (`.png/.jpg/.jpeg/.webp`)
3. The folder is validated locally. `.glb` files are not accepted.
4. On clicking "Envoyer":
   - The app uploads the folder once to a temporary server-side staging area
   - The app prepares the final Git payload from this staging area
   - The app checks the remote Git repo for existing files and computes diffs
   - If the folder doesn't exist, upload proceeds directly
   - If the folder exists and files differ, a confirmation dialog shows **only the actual changes**
   - If nothing changed, the upload is skipped entirely

### Asset naming convention

Texture filenames can either use the internal convention or common GLTF export suffixes. The Git payload is normalized automatically and `model.gltf` texture URIs are rewritten to match the normalized filenames. Drive archiving keeps the original artist files.

Internal convention: use `asset.png` to apply a texture to the whole model, or `asset_object.png` to target a specific object.
Allowed families are defined in `lib/asset-naming.ts`: `color`, `diffuse`, `roughness`, `normal`, `metalness`, `height`, `opacity`, `orm`, `ao`.
Valid internal examples: `color.png`, `diffuse_lampe.png`, `normal_cable1.png`, `opacity_lampe.png`.
Accepted export examples: `lampe_baseColor.png`, `lampe_base_color.png`, `lampe_normal_opengl.png`, `lampe_metallic.png`, `lampe_occlusionRoughnessMetallic.png`, `lampe_mixed_ao.png`.
Git normalization examples: `lampe_baseColor.png` becomes `color_lampe.png`, `lampe_metallic.png` becomes `metalness_lampe.png`, `lampe_occlusionRoughnessMetallic.png` becomes `orm_lampe.png`, and `lampe_mixed_ao.png` becomes `ao_lampe.png`.
Invalid or unknown asset names still block the upload.

### Upload flow: Drive first, then Git

5. **Drive upload (archiving)** — Original files from the staging area are uploaded to the Nextcloud Drive with automatic versioning (see below). This serves as the artists' source of truth and version history. If the Drive upload fails, a modal asks the user whether to send to Git only or cancel entirely.
6. **Git upload (delivery to devs)** — The prepared Git payload is reused from staging: `model.gltf` and `.bin` files are preserved, textures are compressed server-side, then all changed files are pushed to GitHub in a single commit. This is what the dev team consumes in the application.

### Drive versioning (Nextcloud WebDAV)

The Drive uses a `VF` (version finale) / `Vx` (archived versions) structure:

```
Models/
  VF/                    ← latest version
    coffeetest/
      model.gltf
      model.bin
      color.jpg
  V1/                    ← first archive
    coffeetest/
  V2/                    ← second archive
    coffeetest/
```

- **New folder** (doesn't exist in `VF/`): files are uploaded directly to `VF/{folderName}/`
- **Replace** (folder exists in `VF/` with diffs): `VF/{folderName}` is moved to `Vx/{folderName}` (next available version), then all files are re-uploaded to `VF/{folderName}/`
- **No changes**: nothing happens on the Drive

All files are uploaded to `VF/` (not just diffs), because the move operation empties the previous folder.

### Upload safeguards

- The upload flow prevents duplicate submissions on the client (`Envoyer`, overwrite confirmation, and "Git only" confirmation are locked while processing)
- The server applies a lightweight per-folder lock on Drive and Git routes to avoid duplicate commits and concurrent writes
- The folder is staged server-side so the browser sends the payload only once during the full upload flow
- Invalid `model.gltf` JSON or malformed `buffers` entries block the upload before remote writes
- Git LFS uploads are batched in groups of 100 objects to stay within the GitHub LFS Batch API limit

### Commit messages

All changes are pushed in a **single commit** with a grouped formatted message:

**New folder:**
```
update: upload-gltf add a new model -> my-model

📦 Model
  ✅ model.gltf
🎨 Textures (color)
  ✅ color_porte.jpg (compressed)

🪶 Textures (roughness)
  ✅ roughness_tuyaux.png (compressed)

🧩 Assets
  ✅ model.bin
  ✅ opacity_fenetre.png (compressed)
```

**Update (only one texture changed):**
```
update: upload-gltf update -> coffeetest

📦 Model
  ↔️ model.gltf

🎨 Textures (color)
  🔄 color_tuyaux.jpg (compressed)
```

Commit sections:

- `📦 Model`
- `🎨 Textures (color)`
- `🪶 Textures (roughness)`
- `🧭 Textures (normal)`
- `🔩 Textures (metalness)`
- `🧩 Assets`
- `🗑 Deleted`

Symbols: `✅` new — `🔄` modified — `↔️` unchanged (model always re-pushed) — `❌` deleted

7. Orphan files (present on remote but not in the new upload) are deleted in the same commit
8. `model.gltf` is pushed as-is so companion files like `model.bin` remain valid

Uploaded models are pushed to `public/models/<folderName>/` in the target repo.

## Limitations

- Large uploads are faster than before because the folder is staged only once, but the Drive upload remains sequential.
- Git LFS batch uploads are sequential by batch.
- Uploads expect a single `model.gltf` file plus optional flat support files (`.bin`, `.png`, `.jpg`, `.jpeg`, `.webp`).

## Project Structure

```
app/
├── api/upload/
│   ├── stage/route.ts     # POST: upload folder once to temporary staging
│   ├── check/route.ts     # POST: prepare staged Git assets and compare with remote files
│   ├── drive/route.ts     # POST: upload staged originals to Nextcloud Drive (VF/Vx versioning)
│   └── git/route.ts       # POST: push staged prepared assets to GitHub
├── globals.css            # Tailwind + CSS variable fonts
├── layout.tsx             # Root layout (next/font/google)
└── page.tsx               # Home page
components/
├── ui/
│   ├── icons.tsx              # Shared SVG icon components
│   └── Modal.tsx              # Shared modal wrapper + ModalActions
├── upload/
│   ├── SecretInput.tsx        # Access key input
│   ├── FolderDropzone.tsx     # Folder drag & drop / picker
│   ├── FolderCard.tsx         # Folder status card (Drive + Git)
│   ├── DriveStatusLine.tsx    # Drive/Git status sub-line
│   ├── WarningBanner.tsx      # Missing texture warnings
│   ├── OverwriteConfirmModal.tsx  # Diff confirmation dialog
│   ├── NoChangesModal.tsx     # "No changes detected" dialog
│   ├── DriveErrorModal.tsx    # "Drive failed, continue?" dialog
│   └── ActionButtons.tsx      # Upload / Cancel / Reset buttons
├── UploadZone.tsx         # Main upload page (rendering only)
├── ModelViewer.tsx        # Lazy wrapper for 3D viewer
└── SceneViewer.tsx        # Three.js Canvas
hooks/
├── useSecret.ts               # Secret key state management
├── useFolderEntries.ts        # Folder entries state management
└── useUploadOrchestrator.ts   # Upload pipeline orchestration (Drive → Git)
lib/
├── constants.ts           # Shared constants and extensions
├── types.ts               # Server types (ParsedFile, FileDiff, staged asset metadata, etc.)
├── client-types.ts        # Client types (FolderEntry, DriveStatus, etc.)
├── upload-api.ts          # Client-side API helpers (stage, check, uploadDrive, uploadGit)
├── guards.ts              # Shared runtime guards and error message helpers
├── diff-files.ts          # File diff classification (new/changed/unchanged/deleted)
├── sanitize.ts            # Filename sanitization
├── auth.ts                # Upload secret validation (timing-safe)
├── github.ts              # Octokit helpers (getRemoteFolder, pushAllToGitHub)
├── nextcloud.ts           # Nextcloud WebDAV client (native fetch, cached config)
├── upload-staging.ts      # Temporary server-side staging and prepared asset reuse
├── upload-lock.ts         # Lightweight in-memory per-folder upload lock
├── asset-classification.ts # Group assets by family for commit messages
├── asset-naming.ts       # Allowed asset families and naming convention helpers
├── commit-message.ts      # Commit message builder
├── parse-upload.ts        # FormData parser + validation
├── validate-folder.ts     # Client-side folder validation (discriminated union)
└── format-bytes.ts        # Byte formatting utility
Dockerfile                 # Multi-stage build: Node 20 slim + tini
docker-entrypoint.sh       # Startup check + launch
```

## Installation

```bash
git clone https://github.com/La-Fabrik-Durable/upload-GLTF.git
cd upload-GLTF
npm install
```

## Configuration

Copy `.env.example` to `.env.local` and fill in the values:

```env
UPLOAD_SECRET_KEY=your-secret-key-here
GITHUB_TOKEN=ghp_your-github-personal-access-token
GIT_BRANCH=main
GIT_REPO_URL=https://github.com/your-org/your-repo.git
# Nextcloud Drive (public share WebDAV)
NEXTCLOUD_URL=https://cloud.example.com
NEXTCLOUD_SHARE_TOKEN=your-public-share-token
NEXTCLOUD_SHARE_PASSWORD=
NEXTCLOUD_BASE_PATH=Models
```

| Variable | Description | Required |
|----------|-------------|----------|
| `UPLOAD_SECRET_KEY` | Secret key for upload authentication | Yes |
| `GITHUB_TOKEN` | GitHub Personal Access Token (fine-grained, `Contents: Read and write`) | Yes |
| `GIT_BRANCH` | Target branch (default: main) | No |
| `GIT_REPO_URL` | Target GitHub repository URL | Yes |
| `NEXTCLOUD_URL` | Nextcloud instance URL | Yes |
| `NEXTCLOUD_SHARE_TOKEN` | Public share token (the part after `/s/` in the share link) | Yes |
| `NEXTCLOUD_SHARE_PASSWORD` | Public share password (empty if none) | No |
| `NEXTCLOUD_BASE_PATH` | Root folder on the Drive (default: `Models`) | No |

> To create a GitHub token: GitHub > Settings > Developer settings > Fine-grained personal access tokens > select the target repo > Permissions > Contents: Read and write

> To create a Nextcloud public share token: Nextcloud > Files > select folder > Share > Create public share > set permissions (write access required) > copy the share link and extract the token

### Production (Coolify / Docker)

```bash
docker build -t upload-gltf .
docker run -p 3000:3000 \
  -e UPLOAD_SECRET_KEY=your-key \
  -e GITHUB_TOKEN=ghp_xxx \
  -e GIT_REPO_URL=https://github.com/org/repo.git \
  -e NEXTCLOUD_URL=https://cloud.example.com \
  -e NEXTCLOUD_SHARE_TOKEN=your-share-token \
  upload-gltf
```

The Docker image runs the Next.js app and server-side asset preparation in a single container. The `docker-entrypoint.sh` script checks for required environment variables before launching the app

## Supported Formats

| Type | Extensions |
|------|------------|
| 3D Models | `.gltf` |
| Binary buffers | `.bin` |
| Textures | `.png`, `.jpg`, `.jpeg`, `.webp` |

## License

See [MIT](LICENSE) License 

Copyright 2026 La Fabrik Durable. All rights reserved.