fusero-app-boilerplate/README.md

Fusero App Boilerplate

A full-stack application boilerplate with React frontend and Node.js backend.

Project Structure

fusero-app-boilerplate/
├── frontend/           # React frontend application
├── backend/            # Node.js backend application
├── docker-compose.yml  # Production Docker configuration
└── docker-compose.dev.yml  # Development Docker configuration

Prerequisites

• Node.js (v18 or higher)
• npm (v9 or higher)
• Docker and Docker Compose
• Git

Development Setup

Option 1: Running with Docker (Recommended for Development)

1. Start the Development Environment

   docker-compose -f docker-compose.dev.yml up
   

   This will start:
   • Frontend on http://localhost:3000
   • Backend on http://localhost:14000
   • PostgreSQL database on port 19090

Option 2: Running Services Separately (Recommended for Debugging)

For better debugging experience, you can run the frontend and backend in separate terminal windows:

Terminal 1: Backend Service

cd backend
npm install
npm run dev

The backend will be available at http://localhost:14000

Terminal 2: Frontend Service

cd frontend
npm install
npm run dev

The frontend will be available at http://localhost:3000

Environment Setup

1. Backend Environment

   • Copy .env.example to .env in the backend directory
   • Configure your environment variables:

     PORT=14000
     DB_HOST=localhost
     DB_PORT=19090
     DB_USER=postgres
     DB_PASSWORD=postgres
     DB_NAME=fusero
     JWT_SECRET=your_jwt_secret_key_here
     

2. Frontend Environment

   • Copy .env.example to .env in the frontend directory
   • Set the API base URL:

     VITE_API_BASE_URL=http://localhost:14000/api/v1
     

Production Deployment

1. Build and Run with Docker

   docker-compose up --build
   

2. Environment Variables

   • Ensure all environment variables are properly set in your production environment
   • Never commit .env files to version control

Development Best Practices

1. Running Services Separately

   • For development, it's recommended to run frontend and backend in separate terminal windows
   • This allows for better debugging and hot-reloading
   • You can see logs from each service clearly

2. Code Organization

   • Frontend code should be in the frontend/ directory
   • Backend code should be in the backend/ directory
   • Shared types and utilities should be in their respective directories

3. Version Control

   • Commit package-lock.json files
   • Don't commit .env files
   • Use meaningful commit messages

API Documentation

The backend API is documented using Swagger/OpenAPI. After starting the backend service, you can access the API documentation at:

• Development: http://localhost:14000/api-docs
• Production: http://your-domain/api-docs

Troubleshooting

1. Port Conflicts

   • If you encounter port conflicts, check which services are running:

     docker ps
     

   • Or check for processes using the ports:

     lsof -i :3000
     lsof -i :14000
     

2. Database Issues

   • Ensure PostgreSQL is running and accessible
   • Check database connection settings in .env
   • Verify database migrations are up to date

3. CORS Issues

   • If you see CORS errors, verify the frontend's API base URL
   • Check backend CORS configuration
   • Ensure both services are running on the correct ports

Contributing

1. Create a new branch for your feature
2. Make your changes
3. Submit a pull request
4. Ensure all tests pass
5. Update documentation as needed

License

This project is licensed under the MIT License - see the LICENSE file for details.