feat(ops): add all-in-one start and stop orchestrator scripts for local development

- start.sh: Rewritten to gracefully terminate stale processes, start FastAPI (via direct py311 interpreter path to avoid buffering), poll /api/gaps up to 45 seconds to accommodate local reranker weights loading, and spin up Vite dev server
- stop.sh: Expanded to gracefully terminate both API and Vite frontend server processes and clean up tracking files
- Makefile: Added start/stop orchestrations and mapped api/stop-api targets
- .gitignore: Excluded PID tracking files (.api.pid, .web.pid, *.pid)

.gitignore

@@ -21,6 +21,9 @@ dist/
 # Misc
 temp/
 *.log
+*.pid
+.api.pid
+.web.pid
 
 # Data — reproducible via scripts/download_data.sh, never commit raw bytes
 data/

Makefile

@@ -20,13 +20,17 @@ seed:
 eval:
 	python3.11 eval/run_eval.py
 
-# ── API control targets ───────────────────────────────────────────────────────
-api:
+# ── Services Orchestration ────────────────────────────────────────────────────
+start:
 	bash start.sh
 
-stop-api:
+stop:
 	bash stop.sh
 
+api: start
+
+stop-api: stop
+
 openapi:
 	python3.11 scripts/export_openapi.py
 

start.sh

@@ -1,18 +1,85 @@
 #!/usr/bin/env bash
-# File Objective  : Start the local development API server.
-# Scope           : project root command script.
+# File Objective  : Start all local development services (FastAPI API + Vite Frontend) at once.
+# Scope           : project root orchestrator script.
 # What this file does:
-#   1. Runs the FastAPI app via Uvicorn in reload mode.
-#   2. Redirects output to local logs and records the process PID.
+#   1. Stops any pre-existing processes on ports 8000 and 5173 gracefully.
+#   2. Starts the FastAPI backend with uvicorn via the py311 conda environment.
+#   3. Polls the backend healthcheck up to 15 seconds for verification.
+#   4. Starts the Vite React frontend on port 5173.
+#   5. Writes PIDs to local files (.api.pid, .web.pid) and captures logs (api.log, web.log).
 # What it does not do:
-#   1. Run inside a docker container (pure local bash execution).
+#   1. Manage external database processes (Qdrant/Neo4j).
 
-set -e
+set -eo pipefail
 
-echo "→ Starting Vantage API server on http://localhost:8000"
+echo "======================================================================"
+echo "          Vantage Orchestrator — Services Startup                     "
+echo "======================================================================"
 
-# Run Uvicorn in the background, keeping track of process ID
-uvicorn apps.api.main:app --host 127.0.0.1 --port 8000 --reload > api.log 2>&1 &
+# 1. Stop any pre-existing instances first
+echo "→ [1/5] Terminating any stale services..."
+if [ -f .api.pid ]; then
+    PID=$(cat .api.pid)
+    echo "  - Stopping FastAPI server (PID: $PID)..."
+    kill "$PID" 2>/dev/null || true
+    rm -f .api.pid
+fi
+
+if [ -f .web.pid ]; then
+    PID=$(cat .web.pid)
+    echo "  - Stopping Vite Dev Server (PID: $PID)..."
+    kill "$PID" 2>/dev/null || true
+    rm -f .web.pid
+fi
+
+# Fallback: kill processes on ports directly
+echo "  - Scanning ports 8000 & 5173..."
+kill $(lsof -t -i :8000) 2>/dev/null || true
+kill $(lsof -t -i :5173) 2>/dev/null || true
+echo "  ✓ Clean state achieved."
+
+# 2. Reset log files
+echo "→ [2/5] Cleaning stale logs..."
+rm -f api.log web.log
+touch api.log web.log
+
+# 3. Start the FastAPI API Server
+echo "→ [3/5] Starting FastAPI Server (Port: 8000)..."
+# We run uvicorn through python inside the py311 conda environment directly to avoid conda run buffering
+/Users/sourabh/opt/miniconda3/envs/py311/bin/python -m uvicorn apps.api.main:app --host 127.0.0.1 --port 8000 --reload > api.log 2>&1 &
 echo $! > .api.pid
+echo "  ✓ FastAPI process spawned in background (PID: $(cat .api.pid))"
+
+# 4. Wait for API Server Readiness
+echo -n "→ [4/5] Polling API healthcheck"
+API_READY=false
+for i in {1..45}; do
+    if curl -s "http://127.0.0.1:8000/api/gaps?limit=1" >/dev/null; then
+        API_READY=true
+        break
+    fi
+    echo -n "."
+    sleep 1
+done
+echo ""
+
+if [ "$API_READY" = true ]; then
+    echo "  ✓ API is responding on http://127.0.0.1:8000"
+else
+    echo "  ⚠ API failed to respond within 45 seconds."
+    echo "  - Tail of api.log:"
+    tail -n 15 api.log
+    exit 1
+fi
+
+# 5. Start the Vite React Dev Server
+echo "→ [5/5] Starting Vite Frontend Server (Port: 5173)..."
+npm --prefix apps/web run dev > web.log 2>&1 &
+echo $! > .web.pid
+echo "  ✓ Vite process spawned in background (PID: $(cat .web.pid))"
 
-echo "✓ API server started in background (PID: $(cat .api.pid)). Logs written to api.log"
+echo "======================================================================"
+echo "  ✓ All services launched successfully!"
+echo "  - API Backend  : http://localhost:8000  (Logs: api.log)"
+echo "  - React Web UI : http://localhost:5173  (Logs: web.log)"
+echo "======================================================================"

stop.sh

@@ -1,18 +1,40 @@
 #!/usr/bin/env bash
-# File Objective  : Stop the local development API server.
-# Scope           : project root command script.
+# File Objective  : Stop all local development services (FastAPI API + Vite Frontend).
+# Scope           : project root orchestrator script.
 # What this file does:
-#   1. Looks for the running API server process PID.
-#   2. Gracefully terminates the process and cleans up tracking files.
+#   1. Looks for the running API server process PID and stops it.
+#   2. Looks for the running Vite Dev server process PID and stops it.
+#   3. Cleans up tracking files (.api.pid, .web.pid).
 # What it does not do:
-#   1. Stop docker containers or database instances.
+#   1. Terminate database docker containers (Qdrant/Neo4j).
+
+echo "======================================================================"
+echo "          Vantage Orchestrator — Services Shutdown                    "
+echo "======================================================================"
 
 if [ -f .api.pid ]; then
     PID=$(cat .api.pid)
-    echo "→ Stopping Vantage API server (PID: $PID)..."
+    echo "→ Stopping FastAPI server (PID: $PID)..."
     kill "$PID" 2>/dev/null || true
     rm -f .api.pid
     echo "✓ API server stopped."
 else
-    echo "⚠ No .api.pid file found. API server might not be running."
+    echo "⚠ No .api.pid file found. API server might not be running via PID."
+fi
+
+if [ -f .web.pid ]; then
+    PID=$(cat .web.pid)
+    echo "→ Stopping Vite Frontend server (PID: $PID)..."
+    kill "$PID" 2>/dev/null || true
+    rm -f .web.pid
+    echo "✓ Frontend server stopped."
+else
+    echo "⚠ No .web.pid file found. Frontend server might not be running via PID."
 fi
+
+# Fallback: kill port processes directly if any remaining
+echo "→ Performing final check on ports 8000 & 5173..."
+kill $(lsof -t -i :8000) 2>/dev/null || true
+kill $(lsof -t -i :5173) 2>/dev/null || true
+echo "✓ Clean state achieved."
+echo "======================================================================"