diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 72533a9..b166a71 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -1133,25 +1133,126 @@ def test_yolo_detection_speed(self, sample_frame, performance_config):
 
 ## Development Workflow
 
+### Cross-Platform Setup
+The Makefile automatically detects the correct Python command for your platform:
+- **macOS/Linux**: Uses `python3` and `pip3` if available
+- **Windows**: Falls back to `python` and `pip`
+- **Automatic Detection**: No manual configuration needed
+
+### Step-by-Step Project Setup
+
+#### 1. Clone and Navigate to Project
+```bash
+git clone <repository-url>
+cd python-detector-worker
+```
+
+#### 2. Install Dependencies
+```bash
+# Install production dependencies
+make install
+
+# Install development dependencies (includes testing tools)
+make install-dev
+
+# Check environment information
+make env-info
+```
+
+#### 3. Configure Environment (Optional)
+```bash
+# Copy example configuration (if exists)
+cp config.example.json config.json
+
+# Set environment variables for development
+export DETECTOR_WORKER_ENV=dev
+export DETECTOR_WORKER_PORT=8001
+```
+
+#### 4. Run the Application
+```bash
+# For development (staging port 8001 with auto-reload)
+make run-staging
+
+# For production (port 8000)
+make run-prod
+
+# For debugging (verbose logging on staging port)
+make run-debug
+```
+
+#### 5. Verify Installation
+```bash
+# Check system health
+curl http://localhost:8001/health
+
+# Run basic tests
+make test-fast
+
+# Check code quality
+make lint
+```
+
 ### Development Commands
 
+#### Environment Management
 ```bash
-# Setup
-make install-dev              # Install development dependencies
-make format                   # Format code with black & isort
-make lint                     # Run code linting
+make env-info                 # Show environment information
+make check-deps               # Verify dependency integrity
+make update-deps              # List outdated dependencies
+make freeze                   # Generate requirements-frozen.txt
+```
 
-# Testing
+#### Code Development
+```bash
+# Code quality
+make format                   # Format code with black & isort
+make lint                     # Run code linting (flake8, mypy)
+make quality                  # Run all quality checks
+
+# Application execution
+make run                      # Run production mode (port 8000) with reload
+make run-staging              # Run staging mode (port 8001) with reload
+make run-prod                 # Run production mode (port 8000) without reload
+make run-debug                # Run debug mode (port 8001) with verbose logging
+```
+
+#### Testing Framework
+```bash
+# Test execution
 make test                     # Run all tests with coverage
 make test-unit                # Run unit tests only
 make test-integration         # Run integration tests
 make test-performance         # Run performance benchmarks
-make test-fast                # Run fast tests only
+make test-fast                # Run fast tests only (skip slow markers)
 make test-coverage            # Generate detailed coverage report
+make test-failed              # Rerun only failed tests
 
-# Development
-make run                      # Run the application
-make clean                    # Clean build artifacts
+# CI/CD testing
+make ci-test                  # Run CI-optimized tests
+make ci-quality               # Run CI quality checks
+```
+
+#### Docker Operations
+```bash
+# Container management
+make docker-build             # Build Docker image
+make docker-run               # Run container (production port 8000)
+make docker-run-staging       # Run container (staging port 8001)
+make docker-dev               # Run development container with volume mounts
+```
+
+#### Utilities
+```bash
+# Maintenance
+make clean                    # Clean build artifacts and cache
+make monitor                  # Start system resource monitor
+make profile                  # Run performance profiling
+make version                  # Show application version
+
+# Database utilities (when implemented)
+make db-migrate               # Run database migrations
+make db-reset                 # Reset database to initial state
 ```
 
 ### Using the Test Runner
diff --git a/CLAUDE.md b/CLAUDE.md
index d05925c..4925274 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -375,39 +375,120 @@ make format
 
 ## Development & Deployment
 
-### Local Development Setup
+### Cross-Platform Development Setup
+The project supports cross-platform development with automatic Python command detection:
+- **macOS/Linux**: Automatically uses `python3` and `pip3`
+- **Windows**: Falls back to `python` and `pip`
+- **No manual configuration needed**
+
+### Step-by-Step Setup Guide
+
+#### 1. Clone and Setup
 ```bash
-# Install dependencies
+git clone <repository-url>
+cd python-detector-worker
+
+# Check environment information
+make env-info
+```
+
+#### 2. Install Dependencies
+```bash
+# Install production dependencies
+make install
+
+# Install development dependencies (recommended)
 make install-dev
 
-# Run the application
+# Verify installation
+make check-deps
+```
+
+#### 3. Run the Application
+```bash
+# Development mode (staging port 8001 with auto-reload)
+make run-staging
+
+# Production mode (port 8000 with auto-reload)
 make run
 
-# Run with debug mode
+# Production mode (port 8000 without auto-reload)
+make run-prod
+
+# Debug mode (staging port 8001 with verbose logging)
 make run-debug
+```
 
-# Run tests
-make test
+#### 4. Verify Setup
+```bash
+# Check application health
+curl http://localhost:8001/health   # For staging
+curl http://localhost:8000/health   # For production
 
-# Format code
-make format
+# Run quick tests
+make test-fast
 
-# Run quality checks
-make quality
+# Check code quality
+make lint
+```
+
+### Local Development Commands
+
+#### Application Execution
+```bash
+make run                      # Production mode (port 8000) with reload
+make run-staging              # Staging mode (port 8001) with reload
+make run-prod                 # Production mode (port 8000) without reload  
+make run-debug                # Debug mode (staging port 8001) with verbose logging
+```
+
+#### Code Quality & Testing
+```bash
+# Code formatting and quality
+make format                   # Format code with black & isort
+make lint                     # Run linting (flake8, mypy)
+make quality                  # Run all quality checks
+
+# Testing
+make test                     # Run all tests with coverage
+make test-unit                # Run unit tests only
+make test-integration         # Run integration tests
+make test-performance         # Run performance benchmarks
+make test-fast                # Run fast tests only
+make test-coverage            # Generate detailed coverage report
+
+# Development utilities
+make clean                    # Clean build artifacts
+make env-info                 # Show environment details
+make version                  # Show application version
 ```
 
 ### Docker Deployment
+
+#### Basic Docker Operations
 ```bash
 # Build container
 make docker-build
 
-# Run container
+# Run container (production port 8000)
 make docker-run
 
+# Run container (staging port 8001)
+make docker-run-staging
+
 # Development container with volume mounts
 make docker-dev
 ```
 
+#### Docker Environment Variables
+```bash
+# Run with custom port
+docker run -p 8001:8001 -e DETECTOR_WORKER_PORT=8001 detector-worker
+
+# Run with configuration
+docker run -v $(PWD)/config.json:/app/config.json detector-worker
+```
+
 ### Configuration Management
 - **Environment Variables**: Override default configuration
 - **config.json**: Development and production settings
diff --git a/Makefile b/Makefile
index c48fd70..bd90d19 100644
--- a/Makefile
+++ b/Makefile
@@ -1,7 +1,15 @@
 # Detector Worker Makefile
 # Provides convenient commands for development, testing, and deployment
 
-.PHONY: help install install-dev test test-unit test-integration test-performance test-all test-fast test-coverage lint format clean run docker-build docker-run
+# Cross-platform Python command detection
+PYTHON := $(shell command -v python3 2> /dev/null || command -v python 2> /dev/null || echo "python")
+PIP := $(shell command -v pip3 2> /dev/null || command -v pip 2> /dev/null || echo "pip")
+
+# Environment configuration
+PORT_PROD := 8000
+PORT_STAGING := 8001
+
+.PHONY: help install install-dev test test-unit test-integration test-performance test-all test-fast test-coverage lint format clean run run-staging run-prod docker-build docker-run
 
 # Default target
 help:
@@ -25,7 +33,9 @@ help:
 	@echo "  make quality      Run all quality checks"
 	@echo ""
 	@echo "Development:"
-	@echo "  make run          Run the detector worker"
+	@echo "  make run          Run the detector worker (production - port 8000)"
+	@echo "  make run-staging  Run the detector worker (staging - port 8001)"
+	@echo "  make run-prod     Run the detector worker (production - port 8000)"
 	@echo "  make clean        Clean build artifacts"
 	@echo ""
 	@echo "Docker:"
@@ -34,32 +44,32 @@ help:
 
 # Installation targets
 install:
-	pip install -r requirements.txt
+	$(PIP) install -r requirements.txt
 
 install-dev: install
-	pip install -r requirements-dev.txt
+	$(PIP) install -r requirements-dev.txt
 
 # Testing targets
 test:
-	python scripts/run_tests.py --all
+	$(PYTHON) scripts/run_tests.py --all
 
 test-unit:
-	python scripts/run_tests.py --unit --verbose
+	$(PYTHON) scripts/run_tests.py --unit --verbose
 
 test-integration:
-	python scripts/run_tests.py --integration --verbose
+	$(PYTHON) scripts/run_tests.py --integration --verbose
 
 test-performance:
-	python scripts/run_tests.py --performance --verbose
+	$(PYTHON) scripts/run_tests.py --performance --verbose
 
 test-fast:
-	python scripts/run_tests.py --fast --verbose
+	$(PYTHON) scripts/run_tests.py --fast --verbose
 
 test-coverage:
-	python scripts/run_tests.py --coverage --open-browser
+	$(PYTHON) scripts/run_tests.py --coverage --open-browser
 
 test-failed:
-	python scripts/run_tests.py --failed --verbose
+	$(PYTHON) scripts/run_tests.py --failed --verbose
 
 # Code quality targets  
 lint:
@@ -75,14 +85,24 @@ format:
 	isort detector_worker tests scripts
 
 quality: lint
-	python scripts/run_tests.py --quality
+	$(PYTHON) scripts/run_tests.py --quality
 
 # Development targets
 run:
-	python app.py
+	@echo "Running Detector Worker on production port $(PORT_PROD)..."
+	$(PYTHON) -m uvicorn app:app --host 0.0.0.0 --port $(PORT_PROD) --reload
+
+run-staging:
+	@echo "Running Detector Worker on staging port $(PORT_STAGING)..."
+	$(PYTHON) -m uvicorn app:app --host 0.0.0.0 --port $(PORT_STAGING) --reload
+
+run-prod:
+	@echo "Running Detector Worker on production port $(PORT_PROD)..."
+	$(PYTHON) -m uvicorn app:app --host 0.0.0.0 --port $(PORT_PROD)
 
 run-debug:
-	python app.py --debug
+	@echo "Running Detector Worker in debug mode on port $(PORT_STAGING)..."
+	$(PYTHON) -m uvicorn app:app --host 0.0.0.0 --port $(PORT_STAGING) --reload --log-level debug
 
 clean:
 	@echo "Cleaning build artifacts..."
@@ -103,17 +123,20 @@ docker-build:
 	docker build -t detector-worker .
 
 docker-run:
-	docker run -p 8000:8000 detector-worker
+	docker run -p $(PORT_PROD):$(PORT_PROD) detector-worker
+
+docker-run-staging:
+	docker run -p $(PORT_STAGING):$(PORT_STAGING) -e DETECTOR_WORKER_PORT=$(PORT_STAGING) detector-worker
 
 docker-dev:
-	docker run -it -v $(PWD):/app -p 8000:8000 detector-worker bash
+	docker run -it -v $(PWD):/app -p $(PORT_PROD):$(PORT_PROD) detector-worker bash
 
 # CI/CD targets
 ci-test:
-	python scripts/run_tests.py --all --skip-slow
+	$(PYTHON) scripts/run_tests.py --all --skip-slow
 
 ci-quality:
-	python scripts/run_tests.py --quality
+	$(PYTHON) scripts/run_tests.py --quality
 
 # Documentation targets
 docs:
@@ -121,19 +144,19 @@ docs:
 
 # Development utilities
 check-deps:
-	pip check
+	$(PIP) check
 
 update-deps:
-	pip list --outdated
+	$(PIP) list --outdated
 
 freeze:
-	pip freeze > requirements-frozen.txt
+	$(PIP) freeze > requirements-frozen.txt
 
 # Performance profiling
 profile:
-	python -m cProfile -o profile_output.prof app.py
+	$(PYTHON) -m cProfile -o profile_output.prof app.py
 	@echo "Profile saved to profile_output.prof"
-	@echo "View with: python -m pstats profile_output.prof"
+	@echo "View with: $(PYTHON) -m pstats profile_output.prof"
 
 # Database utilities (if needed)
 db-migrate:
@@ -145,16 +168,20 @@ db-reset:
 # Monitor and debug
 monitor:
 	@echo "Starting system monitor..."
-	python -c "import psutil; import time; [print(f'CPU: {psutil.cpu_percent()}%, Memory: {psutil.virtual_memory().percent}%') or time.sleep(1) for _ in range(60)]"
+	$(PYTHON) -c "import psutil; import time; [print(f'CPU: {psutil.cpu_percent()}%, Memory: {psutil.virtual_memory().percent}%') or time.sleep(1) for _ in range(60)]"
 
 # Utility targets
 version:
-	python -c "import detector_worker; print(f'Detector Worker Version: {getattr(detector_worker, \"__version__\", \"unknown\")}')"
+	$(PYTHON) -c "import detector_worker; print(f'Detector Worker Version: {getattr(detector_worker, \"__version__\", \"unknown\")}')"
 
 env-info:
 	@echo "Environment Information:"
-	@echo "Python: $(shell python --version)"
-	@echo "Pip: $(shell pip --version)"
+	@echo "Python: $(shell $(PYTHON) --version)"
+	@echo "Pip: $(shell $(PIP) --version)"
+	@echo "Python Command: $(PYTHON)"
+	@echo "Pip Command: $(PIP)"
 	@echo "Working Directory: $(PWD)"
+	@echo "Production Port: $(PORT_PROD)"
+	@echo "Staging Port: $(PORT_STAGING)"
 	@echo "Git Branch: $(shell git branch --show-current 2>/dev/null || echo 'Not a git repository')"
 	@echo "Git Commit: $(shell git rev-parse --short HEAD 2>/dev/null || echo 'Not a git repository')"
\ No newline at end of file