Sync

DEV-SCRIPTS-README.md

@@ -0,0 +1,143 @@
+# ColaFlow Development Scripts
+
+This directory contains convenient scripts to start and stop the ColaFlow development environment.
+
+## Available Scripts
+
+### Windows (PowerShell)
+
+#### Start Development Environment
+```powershell
+.\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
+```powershell
+.\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
+```bash
+./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
+```bash
+./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
+```bash
+cd colaflow-api
+dotnet run --project src/ColaFlow.API/ColaFlow.API.csproj
+```
+
+### Frontend
+```bash
+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:
+
+```bash
+# 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:
+
+```bash
+cd colaflow-web
+npm install
+```
+
+## Development Workflow
+
+1. Start the development environment:
+   ```bash
+   ./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:
+   ```bash
+   ./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