🎨 NFT Marketplace Full Stack - Complete Guide

A complete decentralized NFT marketplace built with modern architecture, Web3 integration, and software engineering best practices. The application allows users to connect their wallets, view NFTs from a collection, and perform secure buy and sell operations on the Ethereum testnet.

🎯 Project Objectives

Demonstrate in practice the construction of a complete decentralized application (dApp) with:

Web3 Development and blockchain integration
Wallet Integration (WalletConnect, Wagmi, RainbowKit)
RESTful APIs with Go for high performance
Tokenization and transfer of digital assets (NFTs)
Modular and scalable architecture

🚀 Implemented Features

✅ Core Features

🔗 Connect wallet via Metamask or WalletConnect
📋 List NFTs available in the marketplace
🔍 Display details and metadata of each NFT
💰 Buy NFTs with blockchain transactions
📝 List NFTs for sale (listing via contract)
📊 Simplified transaction history
🗄️ Go API to serve NFT metadata (ERC721 standard)

🚀 Future Features

🎯 NFT Staking
🎨 Dynamic minting via frontend
🌐 IPFS integration for images
⭐ Reputation system for sellers
📈 Analytics dashboard on-chain

🏗️ System Architecture

Frontend (React + Wagmi) <--> Backend (Go REST API) <--> Blockchain (Ethereum testnet)

🔄 Data Flow

Frontend: React with RainbowKit, Wagmi and Viem for wallet connection, listing and NFT purchases
Backend: Go with Fiber serving RESTful endpoints for NFT metadata and transaction recording
Smart Contract: Solidity (ERC721) for NFT issuance, listing and sale, compiled and deployed via Hardhat
Blockchain: Goerli or Sepolia Testnet, accessed via Alchemy or Infura RPC
Storage: JSONs served via local API (can be extended to IPFS)

📦 Technology Stack

Layer	Stack / Tools	Version
Frontend	React, Vite, Wagmi, RainbowKit, Tailwind CSS	React 18+
Backend	Go, Fiber, REST API	Go 1.20+
Smart Contracts	Solidity, Hardhat, OpenZeppelin	Solidity ^0.8.0
Blockchain	Ethereum (Goerli / Sepolia)	-
Infrastructure	Railway / Render (API), Vercel (Web)	-
Wallet Support	Metamask, WalletConnect	-

📁 Project Structure

nft-marketplace/
├── backend/                 # Go API
│   ├── main.go             # Application entry point
│   ├── routes/             # Route definitions
│   │   ├── nft.go         # NFT routes
│   │   └── transaction.go # Transaction routes
│   ├── handlers/           # Business logic
│   │   └── nft_handler.go
│   ├── models/             # Data models
│   │   ├── nft.go
│   │   └── transaction.go
│   ├── middleware/         # Middlewares (CORS, etc.)
│   ├── config/             # Configurations
│   ├── go.mod              # Go dependencies
│   ├── Dockerfile          # Containerization
│   └── railway.json        # Railway deployment
├── frontend/               # React App
│   ├── src/
│   │   ├── components/     # React components
│   │   │   ├── Header.tsx
│   │   │   └── NFTCard.tsx
│   │   ├── pages/          # Application pages
│   │   │   ├── Home.tsx
│   │   │   ├── Marketplace.tsx
│   │   │   ├── NFTDetail.tsx
│   │   │   └── MyNFTs.tsx
│   │   ├── hooks/          # Custom hooks
│   │   ├── utils/          # Utilities
│   │   ├── App.tsx         # Main component
│   │   └── main.tsx        # Entry point
│   ├── package.json        # Node.js dependencies
│   ├── vite.config.ts      # Vite configuration
│   ├── tailwind.config.js  # Tailwind configuration
│   └── tsconfig.json       # TypeScript configuration
├── contracts/              # Smart Contracts
│   ├── NFTToken.sol        # ERC721 contract
│   ├── NFTMarketplace.sol  # Main contract
│   ├── hardhat.config.js   # Hardhat configuration
│   ├── scripts/            # Deployment scripts
│   │   └── deploy.js
│   ├── test/               # Contract tests
│   └── package.json        # Hardhat dependencies
├── docs/                   # Documentation
│   ├── API.md             # API documentation
│   └── DEPLOYMENT.md      # Deployment guide
├── docker-compose.yml      # Container orchestration
├── Makefile               # Automation commands
├── setup.sh               # Setup script
└── README.md              # This file

🛠️ Prerequisites

📋 System Requirements

Node.js 18+ and Yarn/NPM installed
Go 1.20+ with modules enabled
Git for version control
Metamask with testnet (Goerli/Sepolia) configured

🔑 Required Accounts

Alchemy or Infura (RPC endpoint)
Vercel (frontend deployment)
Railway or Render (backend deployment)
GitHub (repository and CI/CD)

💰 Test Resources

Testnet faucet (free ETH for testing)
Hardhat for contract deployment
Etherscan for contract verification

🚀 Quick Setup

1. Clone and Initial Setup

git clone <repository-url>
cd nft-marketplace

# Automatic setup (Linux/Mac)
./setup.sh

# Or manual setup
make setup

2. Configure Environment Variables

Backend (.env)

cd backend
cp env.example .env

PORT=8080
ENVIRONMENT=development
CORS_ORIGIN=http://localhost:3000

Frontend (.env)

cd frontend
cp env.example .env

VITE_API_URL=http://localhost:8080
VITE_CONTRACT_ADDRESS=your_deployed_contract_address
VITE_CHAIN_ID=11155111  # Sepolia

Smart Contracts (.env)

cd contracts
cp env.example .env

PRIVATE_KEY=your_private_key
ALCHEMY_API_KEY=your_alchemy_key
ETHERSCAN_API_KEY=your_etherscan_key

3. Deploy Smart Contracts

cd contracts
npm install
npx hardhat compile
npx hardhat run scripts/deploy.js --network sepolia

4. Start Backend

cd backend
go mod tidy
go run main.go

5. Start Frontend

cd frontend
npm install
npm run dev

🌐 Access URLs

Frontend: http://localhost:3000 (or 3001 if 3000 is occupied)
Backend API: http://localhost:8080
API Health Check: http://localhost:8080/health

📚 API Endpoints

NFTs

GET /api/v1/nfts - List all NFTs
GET /api/v1/nfts/:id - Get specific NFT
GET /api/v1/nfts/:id/metadata - Get ERC721 metadata
POST /api/v1/nfts - Create new NFT
PUT /api/v1/nfts/:id - Update NFT
DELETE /api/v1/nfts/:id - Delete NFT

Marketplace

GET /api/v1/nfts/marketplace/listings - Listed NFTs
POST /api/v1/nfts/:id/list - List NFT
POST /api/v1/nfts/:id/buy - Buy NFT
DELETE /api/v1/nfts/:id/cancel-listing - Cancel listing

Transactions

GET /api/v1/transactions - List transactions
GET /api/v1/transactions/:id - Get specific transaction
GET /api/v1/transactions/user/:address - User transactions
GET /api/v1/transactions/nft/:tokenId - NFT transactions

🔧 Useful Commands

Development

# Start all services
make dev

# Frontend only
make frontend

# Backend only
make backend

# Tests
make test

# Build
make build

Deployment

# Deploy smart contracts
make deploy-contracts

# Deploy backend
make deploy-backend

# Deploy frontend
make deploy-frontend

🔐 Security

Smart Contracts

Reentrancy protection in contracts
Input validation and security checks
Pausability for emergencies
Ownership controls for administrative functions

Backend

Input sanitization in all APIs
Rate limiting to prevent spam
CORS properly configured
Wallet validation before sensitive operations

Frontend

Connected wallet validation before interactions
Error boundaries for error handling
Loading states for better UX
HTTPS required in production

🧪 Testing

Smart Contracts

cd contracts
npx hardhat test
npx hardhat coverage

Backend

cd backend
go test ./...
go test -v -cover ./...

Frontend

cd frontend
npm test
npm run test:coverage

🚀 Deployment

Frontend (Vercel)

cd frontend
npm run build
# Deploy to Vercel via GitHub integration

Backend (Railway/Render)

cd backend
# Configure environment variables
# Deploy via Railway or Render dashboard

Smart Contracts

cd contracts
npx hardhat run scripts/deploy.js --network mainnet
npx hardhat verify --network mainnet CONTRACT_ADDRESS

🏆 Technical Differentiators

Strengths

Modular project with clear separation between layers
Go backend code ideal for high performance
Ethereum standards usage (ERC721) and compatible metadata
Real integration with testnet via popular wallets
Extensible architecture for production

Performance

Redis cache for NFT metadata
Lazy loading of images in frontend
Query optimization in backend
CDN for static assets

🤝 Contributing

Fork the project
Create a branch for your feature (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Code Standards

Go: Use gofmt and golint
React: Use ESLint and Prettier
Solidity: Use Solhint
Commits: Use conventional commits

📄 License

This project is under the MIT license. See the LICENSE file for more details.

🆘 Support

If you encounter any problems or have questions:

Check the documentation in docs/
Open an issue on GitHub
Consult the guide QUICK-START.md
Use the Makefile for common commands

🙏 Acknowledgments

OpenZeppelin for secure contracts
Wagmi for Web3 integration
RainbowKit for wallet UI
Fiber for Go framework
Tailwind CSS for styling
Vite for modern build tool

📈 Roadmap

Phase 1 - MVP ✅

Basic smart contracts
Simple Go API
Basic React frontend
Web3 integration

Phase 2 - Improvements 🚧

Royalty system
IPFS integration
Analytics dashboard
E2E tests

Phase 3 - Scalability 🎯

Layer 2 support
Multi-chain
Mobile app
DAO governance

🎯 Ready to start? Follow the setup instructions above and start exploring the world of NFTs! For specific implementation questions, consult the development guide.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github/workflows		.github/workflows
backend		backend
contracts		contracts
docs		docs
frontend		frontend
.editorconfig		.editorconfig
.gitignore		.gitignore
DEPLOYMENT-GUIDE.md		DEPLOYMENT-GUIDE.md
Makefile		Makefile
QUICK-START.md		QUICK-START.md
README.md		README.md
docker-compose.yml		docker-compose.yml
setup-local.sh		setup-local.sh
setup.sh		setup.sh

abrahao-dev/nft-marketplace

Folders and files

Latest commit

History

Repository files navigation

🎨 NFT Marketplace Full Stack - Complete Guide

🎯 Project Objectives

🚀 Implemented Features

✅ Core Features

🚀 Future Features

🏗️ System Architecture

🔄 Data Flow

📦 Technology Stack

📁 Project Structure

🛠️ Prerequisites

📋 System Requirements

🔑 Required Accounts

💰 Test Resources

🚀 Quick Setup

1. Clone and Initial Setup

2. Configure Environment Variables

Backend (.env)

Frontend (.env)

Smart Contracts (.env)

3. Deploy Smart Contracts

4. Start Backend

5. Start Frontend

🌐 Access URLs

📚 API Endpoints

NFTs

Marketplace

Transactions

🔧 Useful Commands

Development

Deployment

🔐 Security

Smart Contracts

Backend

Frontend

🧪 Testing

Smart Contracts

Backend

Frontend

🚀 Deployment

Frontend (Vercel)

Backend (Railway/Render)

Smart Contracts

🏆 Technical Differentiators

Strengths

Performance

🤝 Contributing

Code Standards

📄 License

🆘 Support

🙏 Acknowledgments

📈 Roadmap

Phase 1 - MVP ✅

Phase 2 - Improvements 🚧

Phase 3 - Scalability 🎯

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages