muse-fullstack-dapp

Complete monorepo for the Muse AI Art Marketplace. Includes React frontend, Node.js backend, and Rust smart contracts for decentralized art commerce.

🚀 Quick Start

Prerequisites

• Node.js >= 18.0.0
• npm >= 9.0.0
• MongoDB (local, Docker, or MongoDB Atlas)
• Redis (optional, for caching)

1. Clone the Repository

git clone https://github.com/Muse-AI-Generated-Art-Marketplace/muse-fullstack-dapp.git
cd muse-fullstack-dapp

2. Install Dependencies

npm install

3. Configure Environment Variables

This is the most important step! The application requires environment configuration for database, API keys, and blockchain settings.

Quick Setup

# Copy environment templates
cp .env.example .env
cp apps/backend/.env.example apps/backend/.env
cp apps/frontend/.env.example apps/frontend/.env

# Edit files with your configuration
nano apps/backend/.env      # or use your preferred editor
nano apps/frontend/.env

Validate Configuration

npm run validate-env

4. Start Development Server

npm run dev

This starts:

• Frontend: http://localhost:3000
• Backend: http://localhost:3001
• MongoDB: Required at mongodb://localhost:27017/muse

---

📋 Environment Configuration

The application requires environment variables in three main areas:

Backend (apps/backend/.env)

# Server
PORT=3001
NODE_ENV=development

# Database
MONGODB_URI=mongodb://localhost:27017/muse

# Authentication
JWT_SECRET=your_secure_secret_here_min_32_chars

# Blockchain
STELLAR_NETWORK=testnet
STELLAR_RPC_URL=https://soroban-testnet.stellar.org
STELLAR_CONTRACT_ID=CA...

# AI Services
OPENAI_API_KEY=sk-...
STABILITY_API_KEY=sk-...

Frontend (apps/frontend/.env)

VITE_API_URL=http://localhost:3001
VITE_ENVIRONMENT=development

Required Services

• MongoDB: Database for user and artwork data
• Redis (optional): Caching layer (falls back to in-memory)

Quick Setup with Docker

# MongoDB
docker run -d -p 27017:27017 --name mongo mongo:6

# Redis (optional)
docker run -d -p 6379:6379 --name redis redis:7

For detailed environment setup instructions, see ENVIRONMENT_SETUP.md

---

📁 Project Structure

muse-fullstack-dapp/
├── apps/
│   ├── backend/           # Express.js REST API
│   ├── frontend/          # React + TypeScript + Vite
│   └── web/               # Secondary web app
├── packages/
│   └── contracts/         # Stellar Soroban smart contracts
├── scripts/
│   └── validate-env.js    # Environment validator
├── ENVIRONMENT_SETUP.md   # Detailed environment guide
└── package.json           # Root workspace config

apps/backend

• Express.js REST API server
• MongoDB database integration
• JWT authentication
• Stellar blockchain integration
• AI service integration (OpenAI, Stability AI)
• Redis caching layer

apps/frontend

• React 18 with TypeScript
• Vite build tool
• Tailwind CSS styling
• Stellar wallet integration (Freighter)
• Artwork gallery and minting interface

packages/contracts

• Stellar Soroban smart contracts (Rust)
• NFT minting functionality
• Marketplace smart contract logic

---

🛠️ Development

Available Commands

# Start all services in development mode
npm run dev

# Start individual services
npm run dev:backend
npm run dev:frontend
npm run dev:web

# Build for production
npm run build
npm run build:backend
npm run build:frontend

# Run tests
npm run test

# Run linter
npm run lint

# Validate environment configuration
npm run validate-env

# Clean all dependencies
npm run clean

Testing

# Run all tests
npm run test

# Run specific workspace tests
npm run test --workspace=muse-backend
npm run test --workspace=muse-frontend

Backend Development

cd apps/backend
npm run dev          # Start development server
npm run test         # Run tests with .env.test
npm run build        # Build for production

Frontend Development

cd apps/frontend
npm run dev          # Start Vite dev server
npm run build        # Build for production
npm run preview      # Preview production build

---

🔐 Security Considerations

Environment Variables

⚠️ CRITICAL: Never commit .env files to version control

• .env files are already in .gitignore
• Each environment (dev, staging, prod) should have unique secrets
• Rotate secrets regularly in production
• Use strong random values for JWT_SECRET

Generate Secure Secrets

# Generate JWT secret (min 32 characters)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Recommended Secret Management

• Development: .env file (not committed)
• Staging/Production: Use platform-specific secrets:
  • GitHub Actions: Secrets tab
  • Vercel/Netlify: Environment variables
  • AWS: Secrets Manager or Parameter Store
  • HashiCorp Vault: For enterprise

---

🗄️ Database Setup

MongoDB Options

Option 1: Local Installation

# macOS
brew install mongod

# Linux (Ubuntu)
sudo apt-get install mongodb

# Start service
mongod

Option 2: Docker

docker run -d -p 27017:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=password \
  --name mongo mongo:6

Option 3: MongoDB Atlas (Cloud)

1. Create free account at https://www.mongodb.com/cloud/atlas
2. Create cluster and database
3. Get connection string
4. Update MONGODB_URI in .env

MONGODB_URI=mongodb+srv://user:password@cluster.mongodb.net/muse?retryWrites=true&w=majority

---

⛓️ Blockchain Configuration

Stellar Network

The application uses Stellar Soroban for smart contracts.

Testnet Setup

STELLAR_NETWORK=testnet
STELLAR_RPC_URL=https://soroban-testnet.stellar.org

1. Create Stellar testnet account: https://laboratory.stellar.org
2. Request testnet XLM from faucet
3. Deploy contract to testnet
4. Add contract address to STELLAR_CONTRACT_ID

API Keys

OpenAI (for AI art generation)

1. Sign up: https://platform.openai.com
2. Get API key: https://platform.openai.com/api-keys
3. Set spending limits
4. Add to .env: OPENAI_API_KEY=sk-...

Stability AI (for image generation)

1. Sign up: https://api.stability.ai
2. Get API key
3. Add to .env: STABILITY_API_KEY=sk-...

---

📝 API Documentation

Backend API documentation is available at:

• Development: http://localhost:3001/api/docs (if Swagger configured)
• Health Check: http://localhost:3001/health

Key Endpoints

# Health check
curl http://localhost:3001/health

# Authentication
curl -X POST http://localhost:3001/auth/login

# Artworks
curl http://localhost:3001/api/artworks

# Minting
curl -X POST http://localhost:3001/api/mint

---

🐛 Troubleshooting

Common Issues

1. "Cannot find module" or dependencies error

rm -rf node_modules package-lock.json
npm install

2. "MongoDB connection refused"

# Check MongoDB is running
mongosh

# Or start with Docker
docker run -d -p 27017:27017 mongo:6

# Update .env
MONGODB_URI=mongodb://localhost:27017/muse

3. "JWT_SECRET undefined"

# Generate secure secret
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# Add to apps/backend/.env
JWT_SECRET=<generated-value>

4. "Port already in use"

# Change in .env
PORT=3002  # or another available port

# Kill process on port
lsof -i :3001
kill -9 <PID>

5. CORS errors - frontend can't reach backend

• Check VITE_API_URL matches backend URL
• Check FRONTEND_URL in backend .env for CORS origin
• Check backend is running on correct port

See ENVIRONMENT_SETUP.md#troubleshooting for more solutions.

---

📚 Documentation

• ENVIRONMENT_SETUP.md - Comprehensive environment configuration guide
• CACHING_STRATEGY.md - Caching implementation details
• HEALTH_CHECK_IMPLEMENTATION.md - Health check endpoints
• DATABASE_INDEXING_STRATEGY.md - Database optimization
• ERROR_HANDLING.md - Error handling patterns

---

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/name
3. Make changes and test: npm run validate-env && npm run test
4. Commit with descriptive message
5. Push and create Pull Request

---

📄 License

MIT License - See LICENSE file for details

---

🆘 Support

For issues and questions:

1. Check Documentation: ENVIRONMENT_SETUP.md
2. GitHub Issues: Report issues
3. Discussions: Ask questions

---

🙏 Acknowledgments

Built with:

• Node.js & Express.js
• React & Vite
• MongoDB & Redis
• Stellar Soroban
• OpenAI & Stability AI

---

Last Updated: March 27, 2026