dev.md

Development Guide - 3Dēx

This document serves as the primary technical reference and architectural blueprint for the 3Dēx project.

---

Table of Contents

1. Project Overview
2. Tech Stack Overview
3. Core Principles & Coding Philosophy
4. Installation Guide
5. Cloning the Project
6. Project Structure
7. Environment Variables
8. Database Setup (PostgreSQL + Prisma)
9. Running the Project
10. Verification Checklist
11. Git Workflow
12. Working with a New Local Copy
13. Updating an Existing Local Copy
14. Safe Merging Strategy
15. Troubleshooting
16. Roadmap: Full Dockerization
17. Core Operational Rules

---

Project Overview

3Dēx is a completed MVP for a 3D services and asset marketplace featuring:

Frontend: Next.js + Tailwind
Backend: Node.js + Express
Database: PostgreSQL + Prisma

This guide details the setup and development processes to ensure consistent implementation, avoid breaking changes, and maintain a highly readable, predictable codebase.

---

Tech Stack Overview

Layer	Technology
Frontend	Next.js (React), Tailwind CSS
Backend	Node.js, Express
Database	PostgreSQL
ORM	Prisma
Storage	MinIO (S3 Compatible)
AI / Ecosystem	Google Gemini (Dēxie AI)
Version Control	Git + GitHub

---

Core Principles & Coding Philosophy

To maintain sanity and determinism in the codebase, we adhere strictly to the following philosophical rules. Readability > Everything.

1. Flat Logic (Anti-Deep Nesting)

Avoid stacking conditions. Use early returns and clear branching to minimize indentation depth. Bad:

if (user) {
    if (user.isArtist) {
        // do something
    }
}

Good:

if (!user) return;
if (!user.isArtist) return;
// do something

2. Snake_case for System-Level Variables

While JavaScript leans towards camelCase, we prefer snake_case for database fields, API payloads, and system-level configurations to maintain grounded, practical, backend consistency.

3. Optimistic Error Handling

Don't overprotect the code. If a system-level function fails, let it crash or throw visibly so we know exactly where the failure occurred. This is crucial for debugging during development.

const data = await fetchCriticalData();
process(data); // If data is malformed, let it throw.

4. Development Mental Model

• Code is shared across the team.
• Database data is maintained locally and not shared.
• Storage buckets are local for development purposes.
• Secrets must never be committed to version control.
• Features are developed on dedicated branches, never on master.

---

Installation Guide

1. Git

• Windows: git-scm.com/download/win
• Linux: sudo apt install git

Verify: git --version

---

2. Node.js (LTS Version)

• Download from: nodejs.org (Choose the LTS version)

Verify: node -v, npm -v

---

Verify: psql --version, pg_isready

Important

pgvector Extension Required: For Dēxie AI Search to function, your PostgreSQL instance MUST have the pgvector extension installed.

• Windows: Follow pgvector windows instructions.
• Linux: sudo apt install postgresql-15-pgvector (or your version).

Note: Verification depends on whether PostgreSQL is installed as a service.

---

4. MinIO (Optional for local development)

MinIO can be run via Docker to mock AWS S3 locally:

docker run -p 9000:9000 -p 9001:9001 minio/minio server /data --console-address ":9001"

---

Cloning the Project

git clone https://github.com/Schryzon/3Dex.git
cd 3Dex

---

Project Structure

3Dex/
├─ .github/       # CI/CD workflows and Actions
├─ .vscode/       # Workspace settings (linting, formatting)
├─ apps/
│  ├─ backend/    # Express backend (Controllers, Routes, Prisma schema)
│  └─ frontend/   # Next.js frontend (Pages, Components, Contexts)
├─ docs/          # Technical documentation (You are here)
├─ LICENSE        # Project license
└─ README.md      # Main documentation pointer

Avoid adding redundant folders or storing SQLite/database dumps within the repository.

---

Environment Variables

Backend (apps/backend/.env)

Copy apps/backend/.env.example to apps/backend/.env. Key variables to update:

DATABASE_URL="postgresql://YOUR_USERNAME:YOUR_PASSWORD@localhost:5432/threedex"
PORT=4000
JWT_SECRET="your_secure_random_string"
STORAGE_ENDPOINT="http://localhost:9000"
STORAGE_ACCESS_KEY="minioadmin"
STORAGE_SECRET_KEY="minioadmin"
STORAGE_BUCKET="3dex-models"
SB_MIDTRANS_SERVER_KEY="sandbox-midtrans-server-key"
GEMINI_API_KEY="your-google-ai-studio-key"

Frontend (apps/frontend/.env.local)

Copy apps/frontend/.env.local.example to apps/frontend/.env.local. Key variables to update:

NEXT_PUBLIC_API_URL=http://localhost:4000/api
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_MINIO_URL=http://localhost:9000
NEXT_PUBLIC_SB_MIDTRANS_CLIENT_KEY=your_sandbox_key_here

Docker (.env.docker)

For Docker Compose Only. Copy .env.docker.example to .env.docker.

Warning

Never commit .env files. They are included in .gitignore by default.

---

Database Setup (PostgreSQL + Prisma)

If PostgreSQL is not running as a service, start it manually:

pg_ctl start -D $env:PGDATA

Then, from apps/backend:

npm install
npx prisma migrate dev --name init
npx prisma generate

Success indicators:

• PostgreSQL is running without errors.
• Prisma connected successfully and generated the client.

AI Search Maintenance (Dēxie)

After setting up the database and uploading/seeding models, you must generate vectors for AI search:

cd apps/backend
npm run reindex

This script uses MiniLM to embed all approved models for semantic search.

To stop PostgreSQL: pg_ctl stop

---

Running the Project

Backend

cd apps/backend
npm run dev

Health check: Visit http://localhost:4000/health (Expected: { "status": "ok" })

Frontend

cd apps/frontend
npm install
npm run dev

Access via: http://localhost:3000

---

Verification Checklist

• Frontend loads correctly without hydration errors.
• Backend /health endpoint returns "ok".
• No red console errors in the browser dev tools.
• Prisma migrations applied and Prisma Studio (npx prisma studio) can view the schema.
• AI Search: Running npm run reindex completes without errors and "Sparkles" mode works in the catalog.
• NSFW Filters: Changing user preference in profile correctly blurs/hides models in catalog.

---

Git Workflow

Starting a New Task

git checkout dev
git pull origin dev
git checkout -b feature/your-task-name

Saving Progress

git add .
git commit -m "Brief description of changes"
git push -u origin feature/your-task-name

---

Working with a New Local Copy

git clone https://github.com/Schryzon/3Dex.git
cd 3Dex
git checkout dev

Follow the setup steps mentioned above.

---

Updating an Existing Local Copy

git checkout dev
git pull origin dev
git checkout -b feature/new-task

---

Safe Merging Strategy

Step 1: Update the Dev Branch

git checkout dev
git pull origin dev

Step 2: Merge Dev into Feature Branch

git checkout feature/your-task
git merge dev

Resolve any conflicts locally in the feature branch using VS Code's merge editor.

Step 3: Merge into Dev and Push

git checkout dev
git merge feature/your-task
git push origin dev

Step 4: Cleanup

git branch -d feature/your-task
git push origin --delete feature/your-task

---

Troubleshooting

• "Git overwrote my work": Ensure you commit your changes before pulling updates.

  git add .
  git commit -m "wip"
  git pull

• "Prisma connection error": Verify PostgreSQL is running on the expected port (default 5432).

  pg_isready

  If migrating fails with missing modules, verify package versions match or re-run npm install.

• "Missing Midtrans errors in Cart Checkout": Ensure that USE_MOCK_DATA=false inside src/lib/api/services/product.service.ts so the real Midtrans sandbox environment is utilized.

---

Deployment Workflow

The project uses GitHub Actions for CI/CD and PM2 for process management on the production server.

1. GitHub Actions: Whenever designated branches (dev, master) are updated, GitHub Actions uses deploy.yml to trigger continuous deployment.
2. Server (PM2): The application is managed via ecosystem.config.js.

   pm2 start ecosystem.config.js

   Ensure PM2 is installed globally on the target server.

---

Roadmap: Full Dockerization

The project is currently transitioning from a local-first development model to a fully containerized environment for absolute parity between dev and prod.

Status

• Backend Dockerfile (Production-ready)
• Shared PostgreSQL Container
• Frontend Dockerfile (SSR/Next.js multi-stage)
• MinIO Browser & Console Container
• Centralized Docker Networking (Internal communication)
• Unified docker-compose.prod.yml

Next Steps

1. Frontend Integration: Develop an alpine-based image for the Next.js frontend that supports both development (npm run dev) and production (npm run start) modes.
2. MinIO Persistence: Add a dedicated minio service to docker-compose.yml to eliminate the need for manual Docker run commands for storage.
3. Internal API Resolution: Configure Docker's internal DNS so the frontend can resolve api:4000 without exposing ports unnecessarily to the public internet.

---

Core Operational Rules

1. Do not code directly on the master branch.
2. Always branch from the dev branch.
3. Never commit environment variables (.env).
4. Dedicate one branch per task. (Keep pull requests small and focused)
5. Do not share local database data. (Use seed files if necessary)
6. If it breaks, let it crash. (Do not swallow errors silently. Fix the root cause)