Skip to content

DEV_GUIDE.md

Latest commit

 

History

History
319 lines (219 loc) · 6.55 KB

DEV_GUIDE.md

File metadata and controls

319 lines (219 loc) · 6.55 KB
Raw

🎉 CheckmateX Development Environment - Ready! (Auto-Generated)

✅ Setup Complete!

Your development environment is now fully configured and running. Here's what we've set up:

🚀 What's Running

Service Status Port URL
Client (Frontend) ✅ Running 5173 http://localhost:5173
Server (Backend) ✅ Running 52345 http://localhost:52345
MongoDB ✅ Running 27017 localhost:27017
Redis ✅ Running 6379 localhost:6379

📁 Files Created

  • ✅ .vscode/tasks.json - VS Code tasks for easy development
  • ✅ .vscode/launch.json - Debug configurations
  • ✅ .vscode/settings.json - Project-specific settings
  • ✅ .vscode/extensions.json - Recommended extensions
  • ✅ server/.env - Server environment variables
  • ✅ client/.env.development - Client environment variables
  • ✅ docker-compose.dev.yaml - Docker services configuration

🎯 Quick Actions in VS Code

Start/Stop Development Servers

Method 1: Using Tasks (Recommended)

  1. Press Ctrl+Shift+P (Command Palette)
  2. Type "Run Task"
  3. Select from:
    • "Start All (Dev)" - Starts both server and client
    • "Start Server (Dev)" - Server only
    • "Start Client (Dev)" - Client only
    • "Start Docker Services" - Start MongoDB & Redis
    • "Stop Docker Services" - Stop MongoDB & Redis

Method 2: Using Terminal

# Server
cd server
pnpm dev

# Client (in another terminal)
cd client
pnpm dev

🌐 Access Your Application

Open these URLs in your browser:

  1. Frontend Application: http://localhost:5173
  2. Backend API: http://localhost:52345

🛠️ Development Workflow

Making Changes

  1. Edit Files in VS Code
  2. Hot Reload - Changes are automatically reflected
    • Client: Vite hot-reload
    • Server: Nodemon auto-restart

Running Tests

# Server tests
cd server
pnpm test

# Client tests (when available)
cd client
pnpm test

Code Quality

# Format code
pnpm format

# Check linting
pnpm lint

# Fix linting issues
pnpm lint-fix  # (server only)

🐛 Debugging

Debug Server

  1. Go to Run and Debug panel (Ctrl+Shift+D)
  2. Select "Debug Server" from dropdown
  3. Press F5 or click the green play button
  4. Set breakpoints in your code

📦 Adding New Features - Getting Started

1. Understand the Structure

Client (Frontend):

client/src/
├── Components/     # Reusable UI components
├── Pages/          # Page components
├── Features/       # Feature-specific logic
├── Hooks/          # Custom React hooks
├── Utils/          # Utility functions
├── store.js        # Redux store
└── Routes/         # Routing configuration

Server (Backend):

server/src/
├── controllers/    # Request handlers
├── routes/         # API routes
├── models/         # Database models
├── middleware/     # Express middleware
├── service/        # Business logic
├── validation/     # Input validation
└── utils/          # Utility functions

2. Example: Adding a New Feature

Backend (API Endpoint):

  1. Create model in server/src/db/models/
  2. Add validation in server/src/validation/
  3. Create controller in server/src/controllers/
  4. Add route in server/src/routes/

Frontend (UI):

  1. Create component in client/src/Components/
  2. Add page in client/src/Pages/
  3. Configure route in client/src/Routes/
  4. Add Redux slice if needed in client/src/Features/

3. Test Your Changes

  1. Make changes to code
  2. Check browser for frontend changes
  3. Use Thunder Client or Postman for API testing
  4. Check terminal for errors

🔧 Useful VS Code Extensions (Recommended)

VS Code will prompt you to install these. Click "Install" when prompted:

  • ✅ ESLint - Code linting
  • ✅ Prettier - Code formatting
  • ✅ ES7+ React Snippets - React code snippets
  • ✅ Docker - Docker management
  • ✅ MongoDB for VS Code - Database viewer
  • ✅ Thunder Client - API testing (like Postman)

📊 Monitoring & Logs

View Docker Logs

# All containers
docker-compose -f docker-compose.dev.yaml logs -f

# Specific service
docker logs checkmate_mongodb_dev -f
docker logs checkmate_redis_dev -f

View Application Logs

  • Server logs appear in the "Start Server (Dev)" terminal
  • Client logs appear in the "Start Client (Dev)" terminal

🗄️ Database Management

MongoDB

Connect using MongoDB VS Code extension:

  1. Install "MongoDB for VS Code" extension
  2. Connection string: mongodb://localhost:27017
  3. Database: checkmate

Using MongoDB Shell:

docker exec -it checkmate_mongodb_dev mongosh

Redis

Connect using Redis CLI:

docker exec -it checkmate_redis_dev redis-cli

🚨 Troubleshooting

Server won't start

# Check if port is already in use
netstat -ano | findstr :52345

# Kill the process if needed
taskkill /PID <PID> /F

# Restart server
pnpm dev

Client won't start

# Check if port is already in use
netstat -ano | findstr :5173

# Clear Vite cache
cd client
rm -r node_modules/.vite
pnpm dev

MongoDB connection issues

# Check if MongoDB is running
docker ps

# Restart MongoDB
docker restart checkmate_mongodb_dev

# View MongoDB logs
docker logs checkmate_mongodb_dev

Dependencies issues

# Reinstall dependencies
cd server
rm -r node_modules
pnpm install

cd ../client
rm -r node_modules
pnpm install

🎓 Learning Resources

CheckmateX Documentation

Tech Stack Documentation

🤝 Ready to Contribute!

You're all set! Here's what you can do now:

  1. Explore the codebase - Browse through the files
  2. Run the application - See it in action at http://localhost:5173
  3. Make a small change - Try modifying a component

📝 Next Steps

To start developing:

  1. Open http://localhost:5173 in your browser
  2. Check that both terminals are running without errors
  3. Make a small change to test hot-reload
  4. Start building your feature!

Happy coding! 🚀