Improve development environment with Docker Compose profiles

.gitignore

@@ -3,3 +3,4 @@ __pycache__
 .serena
 .claude/settings.local.json
 PRPs/local
+/logs/

CONTRIBUTING.md

@@ -53,8 +53,10 @@ Archon uses true microservices architecture with clear separation of concerns:
 ### Prerequisites
 
 - [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+- [Node.js 18+](https://nodejs.org/) (for hybrid development mode)
 - [Supabase](https://supabase.com/) account (free tier works)
 - [OpenAI API key](https://platform.openai.com/api-keys) or alternative LLM provider
+- (Optional) [Make](https://www.gnu.org/software/make/) for simplified workflows
 - Basic knowledge of Python (FastAPI) and TypeScript (React)
 
 ### Initial Setup
@@ -74,7 +76,11 @@ After forking the repository, you'll need to:
 3. **Start Development Environment**
 
    ```bash
-   docker-compose up --build -d
+   # Using Docker Compose directly
+   docker compose --profile full up --build -d
+
+   # Or using Make (if installed)
+   make dev-docker
    ```
 
 4. **Configure API Keys**
@@ -211,14 +217,17 @@ Test these things using both the UI and the MCP server. This process will be sim
    **Test commands:**
 
    ```bash
-   # Backend tests
-   cd python && python -m pytest
-
-   # Frontend tests
-   cd archon-ui-main && npm run test
+   # Using Make (if installed)
+   make test       # Run all tests
+   make test-fe    # Frontend tests only
+   make test-be    # Backend tests only
+
+   # Or manually
+   cd python && python -m pytest       # Backend tests
+   cd archon-ui-main && npm run test   # Frontend tests
 
    # Full integration test
-   docker-compose up --build -d
+   docker compose --profile full up --build -d
    # Test via UI at http://localhost:3737
    ```
 
@@ -324,7 +333,10 @@ Test these things using both the UI and the MCP server. This process will be sim
 2. **Testing Your Changes**
 
    ```bash
-   # Run Python tests
+   # Using Make (if installed)
+   make test-be
+
+   # Or manually
    cd python && python -m pytest tests/
 
    # Run specific test categories
@@ -334,8 +346,8 @@ Test these things using both the UI and the MCP server. This process will be sim
 
 3. **Code Quality**
    ```bash
-   # We encourage you to use linters for all code
    # Follow service patterns from existing code
+   # Maintain consistency with the codebase
    ```
 
 ### Frontend Development (React)
@@ -353,7 +365,10 @@ Test these things using both the UI and the MCP server. This process will be sim
 2. **Testing Your Changes**
 
    ```bash
-   # Run frontend tests
+   # Using Make (if installed)
+   make test-fe
+
+   # Or manually
    cd archon-ui-main && npm run test
 
    # Run with coverage
@@ -365,7 +380,10 @@ Test these things using both the UI and the MCP server. This process will be sim
 
 3. **Development Server**
    ```bash
-   # For faster iteration, run frontend locally
+   # Using Make for hybrid mode (if installed)
+   make dev  # Backend in Docker, frontend local
+
+   # Or manually for faster iteration
    cd archon-ui-main && npm run dev
    # Still connects to Docker backend services
    ```

Makefile

@@ -0,0 +1,109 @@
+# Archon Makefile - Simple, Secure, Cross-Platform
+SHELL := /bin/bash
+.SHELLFLAGS := -ec
+
+# Docker compose command - prefer newer 'docker compose' plugin over standalone 'docker-compose'
+COMPOSE ?= $(shell docker compose version >/dev/null 2>&1 && echo "docker compose" || echo "docker-compose")
+
+.PHONY: help dev dev-docker stop test test-fe test-be lint lint-fe lint-be clean install check
+
+help:
+	@echo "Archon Development Commands"
+	@echo "==========================="
+	@echo "  make dev        - Backend in Docker, frontend local (recommended)"
+	@echo "  make dev-docker - Everything in Docker"
+	@echo "  make stop       - Stop all services"
+	@echo "  make test       - Run all tests"
+	@echo "  make test-fe    - Run frontend tests only"
+	@echo "  make test-be    - Run backend tests only"
+	@echo "  make lint       - Run all linters"
+	@echo "  make lint-fe    - Run frontend linter only"
+	@echo "  make lint-be    - Run backend linter only"
+	@echo "  make clean      - Remove containers and volumes"
+	@echo "  make install    - Install dependencies"
+	@echo "  make check      - Check environment setup"
+
+# Install dependencies
+install:
+	@echo "Installing dependencies..."
+	@cd archon-ui-main && npm install
+	@cd python && uv sync
+	@echo "✓ Dependencies installed"
+
+# Check environment
+check:
+	@echo "Checking environment..."
+	@node -v >/dev/null 2>&1 || { echo "✗ Node.js not found (require Node 18+)."; exit 1; }
+	@node check-env.js
+	@echo "Checking Docker..."
+	@docker --version > /dev/null 2>&1 || { echo "✗ Docker not found"; exit 1; }
+	@$(COMPOSE) version > /dev/null 2>&1 || { echo "✗ Docker Compose not found"; exit 1; }
+	@echo "✓ Environment OK"
+
+
+# Hybrid development (recommended)
+dev: check
+	@echo "Starting hybrid development..."
+	@echo "Backend: Docker | Frontend: Local with hot reload"
+	@$(COMPOSE) --profile backend up -d --build
+	@set -a; [ -f .env ] && . ./.env; set +a; \
+	echo "Backend running at http://$${HOST:-localhost}:$${ARCHON_SERVER_PORT:-8181}"
+	@echo "Starting frontend..."
+	@cd archon-ui-main && \
+	VITE_ARCHON_SERVER_PORT=$${ARCHON_SERVER_PORT:-8181} \
+	VITE_ARCHON_SERVER_HOST=$${HOST:-} \
+	npm run dev
+
+# Full Docker development
+dev-docker: check
+	@echo "Starting full Docker environment..."
+	@$(COMPOSE) --profile full up -d --build
+	@echo "✓ All services running"
+	@echo "Frontend: http://localhost:3737"
+	@echo "API: http://localhost:8181"
+
+# Stop all services
+stop:
+	@echo "Stopping all services..."
+	@$(COMPOSE) --profile backend --profile frontend --profile full down
+	@echo "✓ Services stopped"
+
+# Run all tests
+test: test-fe test-be
+
+# Run frontend tests
+test-fe:
+	@echo "Running frontend tests..."
+	@cd archon-ui-main && npm test
+
+# Run backend tests
+test-be:
+	@echo "Running backend tests..."
+	@cd python && uv run pytest
+
+# Run all linters
+lint: lint-fe lint-be
+
+# Run frontend linter
+lint-fe:
+	@echo "Linting frontend..."
+	@cd archon-ui-main && npm run lint
+
+# Run backend linter
+lint-be:
+	@echo "Linting backend..."
+	@cd python && uv run ruff check --fix
+
+# Clean everything (with confirmation)
+clean:
+	@echo "⚠️  This will remove all containers and volumes"
+	@read -p "Are you sure? (y/N) " -n 1 -r; \
+	echo; \
+	if [[ $$REPLY =~ ^[Yy]$$ ]]; then \
+		$(COMPOSE) down -v --remove-orphans; \
+		echo "✓ Cleaned"; \
+	else \
+		echo "Cancelled"; \
+	fi
+
+.DEFAULT_GOAL := help