Chore/add setup and contributing docs (#90)

* chore: add dev setup documentation

* Add agents.md files

* simplify contributing documentation

scripts/start_services.sh

@@ -1,6 +1,42 @@
 #!/usr/bin/env bash
 set -e  # Exit on error
 
+###############################################################################
+### ARGUMENT PARSING
+###############################################################################
+
+DEV_MODE=false
+
+show_help() {
+  echo "Usage: $0 [OPTIONS]"
+  echo ""
+  echo "Options:"
+  echo "  --dev     Enable development mode with auto-reload for API changes"
+  echo "  --help    Show this help message"
+  echo ""
+  echo "Examples:"
+  echo "  $0           # Start in production mode"
+  echo "  $0 --dev     # Start in development mode with auto-reload"
+}
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --dev)
+      DEV_MODE=true
+      shift
+      ;;
+    --help|-h)
+      show_help
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1"
+      show_help
+      exit 1
+      ;;
+  esac
+done
+
 ###############################################################################
 ### CONFIGURATION
 ###############################################################################
@@ -15,13 +51,18 @@ BASE_LOG_DIR="$BASE_DIR/logs"           # Base logs directory
 TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
 LOG_DIR="$BASE_LOG_DIR/$TIMESTAMP"      # Timestamped log directory
 LATEST_LINK="$BASE_LOG_DIR/latest"      # Symlink to latest logs
-VENV_PATH="$(dirname "$BASE_DIR")/venv"
+VENV_PATH="$BASE_DIR/venv"
 
 ARQ_WORKERS=${ARQ_WORKERS:-1}
 
 # Log startup
 cd "$BASE_DIR"
-echo "Starting Dograh Services at $(date) in BASE_DIR: ${BASE_DIR}"
+if $DEV_MODE; then
+  echo "Starting Dograh Services (DEV MODE) at $(date) in BASE_DIR: ${BASE_DIR}"
+  echo "Auto-reload enabled for api/ directory changes"
+else
+  echo "Starting Dograh Services at $(date) in BASE_DIR: ${BASE_DIR}"
+fi
 
 ###############################################################################
 ### 1) Load environment variables
@@ -47,10 +88,19 @@ SERVICE_NAMES=(
   "uvicorn"
 )
 
+# Build uvicorn command based on mode
+if $DEV_MODE; then
+  # Dev mode: single worker with auto-reload (--reload is incompatible with --workers > 1)
+  UVICORN_CMD="uvicorn api.app:app --host 0.0.0.0 --port $FASTAPI_PORT --reload --reload-dir api"
+else
+  # Production mode: multiple workers, no reload
+  UVICORN_CMD="uvicorn api.app:app --host 0.0.0.0 --port $FASTAPI_PORT --workers $FASTAPI_WORKERS"
+fi
+
 SERVICE_COMMANDS=(
   "python -m api.services.telephony.ari_manager"
   "python -m api.services.campaign.campaign_orchestrator"
-  "uvicorn api.app:app --host 0.0.0.0 --port $FASTAPI_PORT --workers $FASTAPI_WORKERS"
+  "$UVICORN_CMD"
 )
 
 # Add ARQ workers dynamically
@@ -208,14 +258,21 @@ done
 
 echo
 echo "──────────────────────────────────────────────────"
+if $DEV_MODE; then
+  echo "Mode: DEVELOPMENT (auto-reload enabled)"
+else
+  echo "Mode: PRODUCTION"
+fi
+echo ""
 for name in "${SERVICE_NAMES[@]}"; do
   pid=$(<"$RUN_DIR/$name.pid")
   echo "✓ $name (PID $pid) → $LOG_DIR/$name.log"
 done
+echo ""
 echo "  Rotation: ${LOG_ROTATION_SIZE:-100 MB}"
 echo "  Retention: ${LOG_RETENTION:-7 days}"
 echo "  Compression: ${LOG_COMPRESSION:-gz}"
 echo "Logs: tail -f $LOG_DIR/*.log"
 echo "Rotated logs: ls $LOG_DIR/*.log.*"
-echo "To stop: run this script again or kill -TERM -<PID> for process groups"
+echo "To stop: ./scripts/stop_services.sh"
 echo "──────────────────────────────────────────────────"

scripts/stop_services.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+set -e  # Exit on error
+
+###############################################################################
+### CONFIGURATION
+###############################################################################
+
+# Determine BASE_DIR as parent of the scripts directory
+BASE_DIR="$(cd "$(dirname "$(dirname "${BASH_SOURCE[0]}")")" && pwd)"
+
+RUN_DIR="$BASE_DIR/run"                 # Where we keep *.pid
+
+cd "$BASE_DIR"
+echo "Stopping Dograh Services at $(date) in BASE_DIR: ${BASE_DIR}"
+
+###############################################################################
+### HELPER FUNCTIONS
+###############################################################################
+
+# Function to get all descendant PIDs of a process (children, grandchildren, etc.)
+get_descendants() {
+  local parent_pid=$1
+  local descendants=""
+  local children
+
+  # Get direct children
+  children=$(pgrep -P "$parent_pid" 2>/dev/null || true)
+
+  for child in $children; do
+    # Recursively get descendants of each child
+    descendants="$descendants $child $(get_descendants "$child")"
+  done
+
+  echo "$descendants"
+}
+
+# Function to kill a process and all its descendants
+kill_process_tree() {
+  local pid=$1
+  local signal=$2
+  local descendants
+
+  descendants=$(get_descendants "$pid")
+
+  # Kill children first (bottom-up), then parent
+  for desc_pid in $descendants; do
+    if kill -0 "$desc_pid" 2>/dev/null; then
+      kill "$signal" "$desc_pid" 2>/dev/null || true
+    fi
+  done
+
+  # Kill the parent
+  if kill -0 "$pid" 2>/dev/null; then
+    kill "$signal" "$pid" 2>/dev/null || true
+  fi
+}
+
+###############################################################################
+### STOP SERVICES
+###############################################################################
+
+if [[ ! -d "$RUN_DIR" ]]; then
+  echo "No run directory found at $RUN_DIR"
+  echo "No services appear to be running."
+  exit 0
+fi
+
+# Find all PID files in the run directory
+pid_files=("$RUN_DIR"/*.pid)
+
+# Check if any PID files exist
+if [[ ! -e "${pid_files[0]}" ]]; then
+  echo "No PID files found in $RUN_DIR"
+  echo "No services appear to be running."
+  exit 0
+fi
+
+stopped_count=0
+failed_count=0
+
+for pidfile in "${pid_files[@]}"; do
+  # Extract service name from pidfile path
+  name=$(basename "$pidfile" .pid)
+
+  if [[ -f "$pidfile" ]]; then
+    oldpid=$(<"$pidfile")
+
+    if kill -0 "$oldpid" 2>/dev/null; then
+      echo "Stopping $name (PID $oldpid and all descendants)..."
+
+      # Kill the entire process tree (parent + all descendants)
+      kill_process_tree "$oldpid" "-TERM"
+      sleep 4
+
+      # Check if parent or any descendants are still alive
+      still_alive=false
+      if kill -0 "$oldpid" 2>/dev/null; then
+        still_alive=true
+      else
+        for desc_pid in $(get_descendants "$oldpid"); do
+          if kill -0 "$desc_pid" 2>/dev/null; then
+            still_alive=true
+            break
+          fi
+        done
+      fi
+
+      if $still_alive; then
+        echo "  Warning: $name did not exit cleanly, forcing stop..."
+        kill_process_tree "$oldpid" "-KILL"
+        sleep 1
+
+        # Final check
+        if kill -0 "$oldpid" 2>/dev/null; then
+          echo "  Error: Failed to stop $name (PID $oldpid)"
+          ((failed_count++))
+        else
+          echo "  Stopped $name (forced)"
+          ((stopped_count++))
+        fi
+      else
+        echo "  Stopped $name"
+        ((stopped_count++))
+      fi
+    else
+      echo "Service $name (PID $oldpid) is not running"
+    fi
+
+    rm -f "$pidfile"
+  fi
+done
+
+# Clean up any port tracking files for uvicorn
+rm -f "$RUN_DIR/uvicorn.port" "$RUN_DIR/uvicorn_new.port" "$RUN_DIR/uvicorn_old.pid"
+
+###############################################################################
+### SUMMARY
+###############################################################################
+
+echo
+echo "──────────────────────────────────────────────────"
+echo "Stopped $stopped_count service(s)"
+if [[ $failed_count -gt 0 ]]; then
+  echo "Failed to stop $failed_count service(s)"
+fi
+echo "──────────────────────────────────────────────────"