Skip to content

Latest commit

 

History

History
408 lines (290 loc) · 6.72 KB

dev.md

File metadata and controls

408 lines (290 loc) · 6.72 KB

📘 dev.md — 3Dēx Development Guide

A single source of truth for every baby.

📌 Table of Contents

  1. What Is This Project?
  2. Tech Stack Overview
  3. Before You Start (VERY IMPORTANT)
  4. Install Everything (Windows & Linux)
  5. Clone the Project
  6. Project Structure Explained
  7. Environment Variables (.env)
  8. Database Setup (PostgreSQL + Prisma)
  9. Running the Project
  10. Testing That Everything Works
  11. Daily Git Workflow (NO COLLISIONS)
  12. Working From a NON‑Existing Folder
  13. Working From an EXISTING Folder
  14. Merging Your Work Safely
  15. Common Mistakes & Fixes
  16. Golden Rules (READ THIS TWICE)

What Is This Project?

3Dēx is a completed MVP for a 3D services & asset marketplace with:

Frontend: Next.js + Tailwind

Backend: Node.js + Express

Database: PostgreSQL + Prisma

This document tells you exactly how to become productive without breaking anything.

Tech Stack Overview

Layer Tech

Frontend  ->  Next.js (React), Tailwind CSS
Backend   ->  Node.js, Express
Database  ->  PostgreSQL
ORM       ->  Prisma
Storage   ->  MinIO (S3 Compatible)
Versions  ->  Git + GitHub

Before You Start (VERY IMPORTANT)

🧠 Baby Mental Model

  • Code is shared

  • Database data is NOT shared

  • Storage bucket is NOT shared (local dev)

  • Secrets are NEVER committed

  • We work on branches, not on master

If you don’t understand this yet — it’s okay.

This guide will enforce it for you.

Install Everything (Windows & Linux)

  1. Install Git

Windows: https://git-scm.com/download/win

Linux:

sudo apt install git

Verify:

git --version
  1. Install Node.js (LTS ONLY)

https://nodejs.org (choose LTS)

Verify:

node -v
npm -v
  1. Install PostgreSQL

Windows: https://www.postgresql.org/download/windows/

Linux:

sudo apt install postgresql postgresql-contrib

Verify:

psql --version
pg_isready

Expected:

accepting connections

Note: This is only if you installed PostgreSQL as a service, otherwise you have to start it manually.

  1. Install MinIO (Optional for local dev, prevents errors)

You can run it via Docker:

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

Or just install the binary.

Clone the Project

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

If this works, you are officially a baby developer 👶✨

Project Structure Explained

3Dex/
├─ apps/
│  ├─ frontend/   # Next.js + Tailwind
│  └─ backend/    # Express + Prisma
├─ docs/          # Documentation
├─ dev.md
└─ README.md

❌ Do NOT add random folders

❌ Do NOT put databases here

Environment Variables (.env)

Backend (apps/backend/.env)

Copy apps/backend/.env.example to apps/backend/.env.

DATABASE_URL="postgresql://YOUR_USERNAME:YOUR_PASSWORD@localhost:5432/threedex"
PORT=4000
# ... see .env.example for full list

Frontend (apps/frontend/.env.local)

Copy apps/frontend/.env.local.example to apps/frontend/.env.local.

NEXT_PUBLIC_API_URL=http://localhost:4000
# ... see .env.local.example for full list

Docker (.env.docker)

For Docker Compose Only. Copy .env.docker.example to .env.docker. This file combines both Backend and Frontend variables for the containerized environment.

🚨 NEVER COMMIT THESE FILES They are already in .gitignore.

Database Setup (PostgreSQL + Prisma)

If you're not using PostgreSQL as a service:

pg_ctl start -D "PATH_TO_DATA_FOLDER"

The data folder usually comes with the installation. Its path can be invoked via the following environment variable names:

  • %PGDATA% (Command Prompt)
  • $env:PGDATA (Powershell)
  • $PGDATA (Linux)

Example:

pg_ctl start -D $env:PGDATA

Then, from apps/backend:

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

If this succeeds:

  • PostgreSQL is running

  • Prisma is connected

  • You are safe 🟢

If you want to stop PostgreSQL, do:

pg_ctl stop

Running the Project

Backend

cd apps/backend
npm run dev

Check:

http://localhost:4000/health

Expected:

{ "status": "ok" }

Frontend

cd apps/frontend
npm install
npm run dev

Open:

http://localhost:3000

Testing That Everything Works

Checklist:

[ ] Frontend loads

[ ] Backend /health works

[ ] No red errors

[ ] Prisma migrate ran successfully

If YES → you are fully set up 🎉

Daily Git Workflow (NO COLLISIONS)

Start work

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

Save work

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

Working From a NON‑Existing Folder

If you never cloned before:

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

Then follow setup steps above.

Working From an EXISTING Folder

If you already cloned before:

git checkout dev
git pull origin dev

Then create your feature branch:

git checkout -b feature/new-task

Merging Your Work Safely

Step 1: Update dev

git checkout dev
git pull origin dev

Step 2: Merge dev into your branch

git checkout feature/your-task
git merge dev

Fix conflicts here, not on dev.

Step 3: Merge into dev

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

Step 4: Delete branch

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

Clean. Safe. Professional.

Common Mistakes & Fixes

❌ “Git overwrote my work”

You didn’t commit before pulling.

Fix:

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

❌ “Prisma can’t connect”

Postgres isn’t running or port isn’t 5432.

Fix:

  1. Check if PostgreSQL is running
pg_isready
  1. If not, start it manually at a certain port (-p 5432) Example: (Powershell)
pg_ctl -o "-p 5432" start -D $env:PGDATA

Golden Rules (READ THIS TWICE)

  1. ❌ Never code on master
  2. ✅ Always branch from dev
  3. ❌ Never commit .env
  4. ✅ One task = one branch
  5. ❌ Never share DB data
  6. ✅ Ask mommy before panicking