# Research: Project Launch Script

## Decision: Bash Script with `trap` and Background Processes

### Rationale
A bash script is the most portable and lightweight way to meet the requirement of a single command (`./run.sh`) without introducing additional process management dependencies like `pm2` or `concurrently` (unless we want to use `npm` to run everything, but the user asked for a script).

### Alternatives Considered
1.  **`concurrently` (NPM package)**:
    - *Pros*: Easy to use, handles output well.
    - *Cons*: Requires `npm install` before it can even run. The goal is a script that *handles* the install.
2.  **`docker-compose`**:
    - *Pros*: Perfect for multi-service orchestration.
    - *Cons*: Overkill for a simple local dev environment; requires Docker to be installed and configured.
3.  **Python script**:
    - *Pros*: Better cross-platform support (Windows/Linux).
    - *Cons*: Slightly more verbose for process management than bash on Linux.

## Technical Findings

### 1. Concurrent Execution & Graceful Shutdown
To run processes concurrently and handle Ctrl+C:
```bash
#!/bin/bash

# Cleanup function
cleanup() {
    echo "Stopping services..."
    kill $BACKEND_PID $FRONTEND_PID
    exit
}

# Trap SIGINT (Ctrl+C)
trap cleanup SIGINT

# Start Backend
cd backend && python3 -m uvicorn src.app:app --reload --port 8000 &
BACKEND_PID=$!

# Start Frontend
cd frontend && npm run dev -- --port 5173 &
FRONTEND_PID=$!

# Wait for processes
wait
```

### 2. Dependency Checking
- **Backend**: Check for `venv`. If missing, create it and install requirements.
- **Frontend**: Check for `frontend/node_modules`. If missing, run `npm install`.

### 3. Environment Validation
- Check `command -v python3` and `command -v npm`.

## Best Practices
- Use colors for logs to distinguish between Backend and Frontend output.
- Use `set -e` to exit on error during setup, but disable it or handle it carefully when starting background processes.