🌌 Lucent

Lucent is a next-generation 3D asset pipeline and version control platform engineered specifically for modern web developers. It bridges the gap between raw 3D modeling packages and lightweight, responsive web experiences.

By offloading heavy mesh compression and asset optimization to a blazing-fast Go-based microservice, Lucent optimizes heavy .glb and .fbx files, manages versions with branch-like snapshot histories, stores optimized models securely on Cloudflare R2, and serves them globally via a ultra-fast CDN with ready-to-use boilerplate code snippets.

---

🎯 Project Identity

• What Lucent IS: A pipeline and review tool. It focuses entirely on compressing, optimizing, versioning, inspecting, and serving assets efficiently.
• What Lucent IS NOT: A 3D editor. It does not replace Blender, Maya, or other authoring software, and it is not a general-purpose file host.

---

✨ Core Features

• ⚡ The Nucleus (CGo Mesh Engine): A high-performance Go processor utilizing native meshoptimizer bindings to automate vertex/index simplification, LOD (Level of Detail) generation, and texture compression.
• 👁️ The Prism (Spatial Inspector): A stunning, dark-mode Next.js 15 dashboard built with Tailwind v4, React Three Fiber (R3F), and GSAP. Allows real-time inspection, progressive asset streaming, and version traversal.
• 📌 Spatial Canvas Comments: Pin comments directly to 3D coordinate vectors (XYZ positions and normals) on the model for granular visual reviews and threaded feedback.
• 🌿 Snapshot-Based Versioning: A Git-like version tree for 3D models. Track historical snapshots, view optimization deltas (vertices/polygons saved), and instantly promote/demote production URLs.
• 🚀 Lucent CLI: A robust command-line companion built in Go using Cobra. Upload meshes, monitor processing jobs, fetch CDN links, and automate 3D pipelines directly from CLI or CI/CD pipelines.

---

🛠️ Tech Stack

Frontend ("The Prism")

• Framework: Next.js 15+ (App Router, Strict Mode TypeScript)
• Styling: Tailwind CSS v4
• UI Components: ShadCN UI (Enhanced with Lucent theme overrides)
• 3D Rendering: Three.js, React Three Fiber (R3F), @react-three/drei
• Animation & Motion: GSAP (Advanced choreographies & camera tracks) + Framer Motion (Layout transitions)
• State Management: Zustand
• Real-time status: Server-Sent Events (SSE)

Backend Engine ("The Nucleus")

• Language: Go (Golang 1.26+)
• Framework: HTTP router (Gin / Echo)
• 3D Processing: Custom Go validators, native CGo bindings for meshoptimizer
• Fallback Worker: gltf-pipeline (Node.js) executed via job queue
• Job Queue & Broker: Redis + Asynq
• Database ORM: Drizzle ORM (Next.js client) & Go pgx (processor client)

Infrastructure

• Database: Neon (Serverless PostgreSQL)
• Storage: Cloudflare R2 (S3 API, zero egress fees)
• Authentication: NextAuth.js v5
• Payments: Lemon Squeezy
• Monitoring: Sentry (Errors) + Axiom / Betterstack (Logs)

---

📁 Repository Structure

lucent/
├── apps/
│   └── web/                          # Next.js 15 Front-End application
│       ├── app/                      # Next.js App Router (dashboard, auth, viewer, settings, api)
│       ├── components/               # Themed UI, dashboard, viewer, and code snippets
│       ├── hooks/                    # Reusable React hooks
│       ├── lib/                      # Database config, auth providers, R2 client
│       ├── stores/                   # Zustand stores for state management
│       └── types/                    # Next.js typings
│
├── services/
│   └── processor/                    # High-performance Go microservice
│       ├── cmd/server/               # Server entry point
│       ├── internal/
│       │   ├── api/                  # HTTP handler endpoints
│       │   ├── processor/            # Mesh simplification & LOD generation (CGo meshopt bindings)
│       │   ├── storage/              # R2 client & uploader stream
│       │   ├── queue/                # Asynq queue orchestrator
│       │   ├── validator/            # 3D Magic bytes and structural validation
│       │   └── db/                   # Neon database connection
│       └── pkg/                      # Shared config and utilities
│
├── packages/
│   └── cli/                          # Go-based CLI companion tool
│       ├── cmd/                      # Cobra CLI commands (login, push, ls, url)
│       └── main.go                   # CLI entry point
│
├── docs/                             # Additional developer guides
├── docker-compose.yml                # Docker Compose environment (Redis + Postgres)
├── CLAUDE.md                         # Project Intelligence guidelines
└── README.md                         # This file

---

⚙️ Setup & Installation

1. Prerequisites

Ensure the following tools are installed locally:

• Node.js v20+
• Go v1.26+
• Docker (For local Redis & Postgres services)
• Git

2. Run Infrastructure (Docker)

Start the Redis server (job queue) and serverless-like Postgres environment:

docker-compose up -d

3. Configure Environment Variables

Create a .env file in the root directory (referencing .env.example):

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/lucent

# Cloudflare R2
R2_ACCOUNT_ID=your-account-id
R2_ACCESS_KEY_ID=your-access-key
R2_SECRET_ACCESS_KEY=your-secret-key
R2_BUCKET_NAME=lucent-assets
R2_PUBLIC_URL=https://cdn.lucent.dev

# Auth
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=generate-a-secure-secret-key
GITHUB_CLIENT_ID=your-github-id
GITHUB_CLIENT_SECRET=your-github-secret

# Go Processor Service
GO_SERVICE_URL=http://localhost:8080
GO_SERVICE_API_KEY=internal-secret-api-key

# Redis
REDIS_URL=redis://localhost:6379

4. Run the Web Dashboard ("The Prism")

cd apps/web
npm install
npm run dev

Open http://localhost:3000 to view the UI dashboard.

5. Run the Go Service ("The Nucleus")

Ensure you are in the processor service folder:

cd services/processor
go mod download
go run cmd/server/main.go

The processor service boots up on :8080 and begins listening to Redis job queues.

---

💻 Lucent CLI

The Lucent Command Line Interface enables uploading files, checking background jobs, and obtaining asset CDN URLs from your shell.

Installation

Compile the CLI binary:

cd packages/cli
go build -o lucent main.go

Commands Reference

• Authenticate with the platform:

  ./lucent login --api-key <YOUR_API_KEY> --server-url <SERVER_URL>

  This generates a local configuration file in ~/.lucent/config.json.

• Push a 3D asset for processing:

  ./lucent push path/to/model.glb --project <project-slug-or-id>

  (Note: Stream uploads feature an interactive progress bar and output the Job ID & Asset ID)

• List assets and projects:

  ./lucent ls

• Get the CDN URL for a snapshot:

  ./lucent url <asset-id>

---

📐 Architecture Rules

For developer consistency and performance stability, these 10 rules are strictly enforced:

1. 🚫 No Browser Processing: Do not process or compress 3D meshes in the client browser. All optimization/LOD calculation is done server-side in Go.
2. 🚫 Zero Disk Operations: Uploaded files are streamed directly to Cloudflare R2. Never write raw uploads to local server disks.
3. 🚫 No public/ Folder Writes: Assets are loaded exclusively through secure CDN URLs (https://cdn.lucent.dev/...). Never save uploads locally.
4. 🎨 ShadCN Custom Styling: Standard visual properties of UI elements must include Lucent design system variables and premium glassmorphic attributes.
5. 🚫 R2 Core Dependency: Cloudflare R2 is mandatory for object storage due to zero egress cost constraints. AWS S3 or other storage providers must not be proposed.
6. ⏳ Async Processing Pipeline: All file uploads are tracked via temporary jobs. Next.js receives a Job ID instantly, while Redis + Asynq workers handle mesh simplification asynchronously.
7. 🏗️ Never direct shell-exec gltf-pipeline: gltf-pipeline is run through background Node workers using Redis queues; calling it via exec.Command in Go is strictly prohibited.
8. ⌛ React Suspense Canvas: Wrap all R3F Canvas setups in <Suspense> using stylized bone/wireframe loading skeletons as loaders instead of generic spinners.
9. 🔄 Progressive Loading: Load lowest resolution LOD models first, progressively substituting higher details to decrease initial render latency.
10. 🛡️ Early Input Validation: Custom Go validators verify magic bytes, header structural validity, and user subscription storage quota limits before initiating async workers.

---

🗄️ Database Schema Reference

Table	Key Fields	Purpose
users	id (UUID), subscription_tier, storage_used, storage_limit	User quotas and metric limits (measured in bytes)
api_keys	id, user_id, key_hash, prefix, permissions, expires_at	Platform integration credentials used by the CLI
projects	id, user_id, name, slug, is_public	Virtual container separating user groups/workspaces
assets	id, project_id, base_filename, production_url, asset_type	Logical file wrapper mapping snapshot trees
snapshots	id, asset_id, version_number, r2_url, polygon_count, is_approved, parent_snapshot_id	Core Git-like version tree node mapping physical optimized assets
jobs	id, snapshot_id, status, worker_id, progress, error_message	Status tracking tracker for asynchronous optimization workers
comments	id, snapshot_id, pos_x/y/z, normal_x/y/z, text, parent_id	3D relative pinned comments supporting threaded responses
team_members	id, project_id, user_id, role	Permissions ACL (Roles: owner, editor, viewer)

---

🎨 Design System

Lucent employs an ultra-premium, dark-mode-only aesthetic featuring glassmorphism and soft violet neon glows.

Color Palette

--lucent-base:          #050505; /* Pure dark ground */
--lucent-surface:       #0F0E17; /* Card & sidebar backdrops */
--lucent-surface-hover: #1A1826; /* Hover selections */
--lucent-primary:       #7C3AED; /* Vibrant violet */
--lucent-primary-hover: #6D28D9; /* Deep violet */
--lucent-accent-glow:   #A855F7; /* Glowing indicators */
--lucent-success:       #10B981; /* Emerald green */
--lucent-warning:       #F59E0B; /* Amber warning */
--lucent-destructive:   #EF4444; /* Ruby red */
--lucent-text:          #F5F5F5; /* Crisp text */
--lucent-text-muted:    #A1A1AA; /* Secondary labels */
--lucent-border:        #27272A; /* Slate outlines */
--lucent-glass:         rgba(15, 14, 23, 0.7);
--lucent-glass-border:  rgba(124, 58, 237, 0.15);

Visual and Motion Foundations

• Typography: Inter for user interfaces, JetBrains Mono for system outputs, polygon counts, and JSON codes.
• Shadows: Elevated dialogs use shadow-lg shadow-lucent-primary/10 to yield a fine, purple volumetric shadow.
• Smooth Easing: Use GSAP for advanced camera choreographies, model rotation transitions, and staggered card entries (stagger: 0.05, y: 20, opacity: 0 entering state). Framer Motion is reserved exclusively for simple layout state animations.

---

🧪 Testing

We value code quality and testing accuracy:

• Go Engine: Run unit tests for mesh decimation, validation routines, and streaming.

  cd services/processor
  go test ./...

• Next.js Dashboard: Verify components and routing schemas.

  cd apps/web
  npm run lint

• End-to-End Suite: Playwright automated testing ensures complete stability of the upload → process → render → comment pipelines.

---

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details.