Skip to content

plan.md

Latest commit

 

History

History
90 lines (66 loc) · 4.7 KB

plan.md

File metadata and controls

90 lines (66 loc) · 4.7 KB
Raw

SYSTEM DIRECTIVE: LUCENT PROJECT ARCHITECTURE

1. PROJECT OVERVIEW

Project Name: Lucent Core Purpose: A high-performance 3D asset pipeline and version control platform for creative web developers. Primary Mechanism: Ingest heavy 3D files (.glb/.fbx), process and optimize them via a Go microservice, store them securely with zero-egress fees, and provide developers with a persistent, version-controlled CDN link and ready-to-use Next.js code snippets.

2. TECHNICAL STACK

AI agents must strictly adhere to this stack. Do not suggest alternatives unless explicitly prompted by the user.

Frontend (The "Prism")

  • Framework: Next.js 15 (App Router)
  • Language: TypeScript
  • Styling: Tailwind CSS v4
  • UI Components: ShadCN UI (customized for Glassmorphism)
  • 3D Engine: Three.js + React Three Fiber (R3F) + Drei
  • Animation/Motion: GSAP (Complex UI choreography), Framer Motion (Simple layout shifts)
  • State Management: Zustand

Backend (The "Nucleus")

  • Language/Framework: Go (Golang) with Gin or Echo
  • 3D Processing: gltf-pipeline (via CGo or shell sub-process) for Draco compression and Auto-LOD.
  • Database: Neon (Serverless PostgreSQL)
  • Storage: Cloudflare R2 (S3-compatible API, chosen specifically for $0 egress fees)
  • Authentication: NextAuth.js
  • Payments: Lemon Squeezy

3. DESIGN SYSTEM & AESTHETIC DIRECTIVES

AI agents generating UI code must apply these rules rigidly to maintain the "Lucent" brand authority.

  • Theme: Strict Dark Mode.
  • Color Palette:
    • Background Base: #050505
    • Surface: #0F0E17
    • Primary Accent (Aesthetic Violet): #7C3AED
    • Secondary Glow: #A855F7
    • Success State: #10B981
  • UI Paradigm (Glassmorphism): Sidebars, modals, and floating action bars must use backdrop-filter: blur(12px) over a semi-transparent surface background (rgba(15, 14, 23, 0.7)).
  • Motion: No generic loading spinners. Use GSAP for smooth staggering, spring-based entrances, and seamless 3D camera transitions.

4. CORE LOGIC FLOWS (AI IMPLEMENTATION GUIDE)

Flow A: Asset Ingestion & Optimization (Critical Path)

  1. Upload: Client posts .glb binary to Next.js API route.
  2. Pass-through: Next.js securely pipes the stream to the Go microservice.
  3. Processing: Go service calculates SHA-256 hash (deduplication). Executes gltf-pipeline to compress textures and geometry.
  4. Storage: Go streams the optimized binary directly to Cloudflare R2 bucket.
  5. Database: Go writes a new Snapshot record in Neon Postgres, linking the R2 URL to the parent Project.

Flow B: Spatial Commenting

  1. Raycasting: User clicks on the R3F mesh in the browser.
  2. Vector Capture: Capture intersection XYZ coordinates.
  3. Storage: Save comment text + XYZ vector to Postgres.
  4. Retrieval: On load, map over comments and render small HTML overlays via R3F <Html> component at the precise 3D coordinates.

5. DATABASE SCHEMA (POSTGRESQL)

Agents should use these core tables when generating Prisma/Drizzle schemas or raw SQL.

  • Users: id, email, subscription_tier, storage_used, bandwidth_used
  • Projects: id, user_id, name, created_at
  • Assets: id, project_id, base_filename
  • Snapshots (Versioning): id, asset_id, version_number, r2_url, file_size_bytes, polygon_count, parent_snapshot_id (Self-referencing for history tree)
  • Comments: id, snapshot_id, user_id, text, pos_x, pos_y, pos_z, status

6. STRICT AI RULES & AVOIDANCES

  • DO NOT generate code that processes heavy 3D files in the browser (client-side). All optimization must be routed to the Go backend.
  • DO NOT save files to local disk or Next.js public folders. Always stream directly to Cloudflare R2 to prevent server memory bloat.
  • DO NOT use default ShadCN styling. Always inject the Lucent color variables and blur filters into the component generation.
  • DO NOT propose alternative cloud providers like AWS S3. The architecture relies on Cloudflare R2's specific pricing model.
  • DO wrap 3D canvas components in React <Suspense> boundaries.
  • DO implement progressive loading: load a low-poly or heavily compressed version of the asset first, then swap to high-res.

7. EXECUTION PHASES

When prompted to begin coding, agents should ask the user which phase to execute:

  1. Phase 1: Go Microservice Setup & Cloudflare R2 Connection.
  2. Phase 2: Neon Database Schema & NextAuth Integration.
  3. Phase 3: Next.js 15 App Router Shell & Glassmorphism UI Setup.
  4. Phase 4: R3F Viewer, GSAP Integration, and Spatial Raycasting.
  5. Phase 5: Snippet Generator & Pipeline Visualization Dashboard.