ColaFlow/DEV-SCRIPTS-README.md

ColaFlow Development Scripts

This directory contains convenient scripts to start and stop the ColaFlow development environment.

Available Scripts

Windows (PowerShell)

Start Development Environment

.\start-dev.ps1

This script will:

• Check if backend (port 5000) and frontend (port 3000) are already running
• Start the backend API in a new PowerShell window
• Start the frontend web application in a new PowerShell window
• Display the URLs for accessing the services

Stop Development Environment

.\stop-dev.ps1

This script will:

• Stop all .NET (dotnet.exe) processes
• Stop all Node.js processes running on port 3000
• Clean up gracefully

Linux/macOS/Git Bash (Bash)

Start Development Environment

./start-dev.sh

This script will:

• Check if backend (port 5000) and frontend (port 3000) are already running
• Start the backend API in the background
• Start the frontend web application in the background
• Save process IDs to backend.pid and frontend.pid
• Save logs to backend.log and frontend.log
• Keep running until you press Ctrl+C (which will stop all services)

Stop Development Environment

./stop-dev.sh

This script will:

• Stop the backend and frontend processes using saved PIDs
• Fall back to killing processes by port/name if PIDs are not found
• Clean up log files and PID files

Service URLs

Once started, the services will be available at:

• Backend API: http://localhost:5167 (or the port shown in the startup output)
• Swagger UI: http://localhost:5167/swagger
• Frontend: http://localhost:3000

Manual Startup

If you prefer to start the services manually:

Backend

cd colaflow-api
dotnet run --project src/ColaFlow.API/ColaFlow.API.csproj

Frontend

cd colaflow-web
npm run dev

Troubleshooting

Port Already in Use

If you see errors about ports already being in use:

1. Run the stop script first:

   • Windows: .\stop-dev.ps1
   • Linux/macOS: ./stop-dev.sh

2. Then start again:

   • Windows: .\start-dev.ps1
   • Linux/macOS: ./start-dev.sh

Lock File Issues (Frontend)

If you see "Unable to acquire lock" errors for the frontend:

# Remove the lock file
rm -f colaflow-web/.next/dev/lock

# Then restart
./start-dev.sh  # or .\start-dev.ps1 on Windows

Database Connection Issues

Make sure PostgreSQL is running and the connection string in .env or appsettings.Development.json is correct.

Node Modules Missing

If the frontend fails to start due to missing dependencies:

cd colaflow-web
npm install

Development Workflow

1. Start the development environment:

   ./start-dev.sh  # or .\start-dev.ps1 on Windows
   

2. Make your changes to the code

3. The services will automatically reload when you save files:

   • Backend: Hot reload is enabled for .NET
   • Frontend: Next.js Turbopack provides fast refresh

4. When done, stop the services:

   ./stop-dev.sh  # or .\stop-dev.ps1 on Windows
   

   Or press Ctrl+C if using the bash version of start-dev.sh

Notes

• The PowerShell scripts open new windows for each service, making it easy to see logs
• The Bash scripts run services in the background and save logs to files
• Both sets of scripts check for already-running services to avoid conflicts
• The scripts handle graceful shutdown when possible