Add improved development environment with backend in Docker and front…

.gitignore

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

Makefile

@@ -0,0 +1,99 @@
+# Archon Makefile - Simple, Secure, Cross-Platform
+SHELL := /bin/bash
+.SHELLFLAGS := -ec
+
+.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 check-env.js
+	@echo "Checking Docker..."
+	@docker --version > /dev/null 2>&1 && echo "✓ Docker installed" || echo "✗ Docker not found"
+	@docker-compose --version > /dev/null 2>&1 && echo "✓ Docker Compose installed" || echo "✗ Docker Compose not found"
+
+# Hybrid development (recommended)
+dev: check
+	@echo "Starting hybrid development..."
+	@echo "Backend: Docker | Frontend: Local with hot reload"
+	@docker-compose --profile backend up -d --build
+	@echo "Backend running at http://localhost:8181"
+	@echo "Starting frontend..."
+	@cd archon-ui-main && npm run dev
+
+# Full Docker development
+dev-docker: check
+	@echo "Starting full Docker environment..."
+	@docker-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..."
+	@docker-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 \
+		docker-compose down -v --remove-orphans; \
+		echo "✓ Cleaned"; \
+	else \
+		echo "Cancelled"; \
+	fi
+
+.DEFAULT_GOAL := help

README.md

@@ -43,8 +43,10 @@ This new vision for Archon replaces the old one (the agenteer). Archon used to b
 ### 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 or local Supabase both work)
 - [OpenAI API key](https://platform.openai.com/api-keys) (Gemini and Ollama are supported too!)
+- [Make](https://www.gnu.org/software/make/) (see [Installing Make](#installing-make) below)
 
 ### Setup Instructions
 
@@ -70,13 +72,17 @@ This new vision for Archon replaces the old one (the agenteer). Archon used to b
 
 3. **Database Setup**: In your [Supabase project](https://supabase.com/dashboard) SQL Editor, copy, paste, and execute the contents of `migration/complete_setup.sql`
 
-4. **Start Services**:
+4. **Start Services** (choose one):
+
+   **Full Docker Mode (Recommended for Normal Archon Usage)**
 
    ```bash
-   docker-compose up --build -d
+   docker-compose --profile full up --build -d
+   # or
+   make dev-docker
    ```
 
-   This starts the core microservices:
+   This starts all core microservices in Docker:
    - **Server**: Core API and business logic (Port: 8181)
    - **MCP Server**: Protocol interface for AI clients (Port: 8051)
    - **Agents (coming soon!)**: AI operations and streaming (Port: 8052)
@@ -89,6 +95,19 @@ This new vision for Archon replaces the old one (the agenteer). Archon used to b
    - Go to **Settings** → Select your LLM/embedding provider and set the API key (OpenAI is default)
    - Test by uploading a document or crawling a website
 
+### 🚀 Quick Command Reference
+
+| Command           | Description                                             |
+| ----------------- | ------------------------------------------------------- |
+| `make dev`        | Start hybrid dev (backend in Docker, frontend local) ⭐ |
+| `make dev-docker` | Everything in Docker                                    |
+| `make stop`       | Stop all services                                       |
+| `make test`       | Run all tests                                           |
+| `make lint`       | Run linters                                             |
+| `make install`    | Install dependencies                                    |
+| `make check`      | Check environment setup                                 |
+| `make clean`      | Remove containers and volumes (with confirmation)       |
+
 ## 🔄 Database Reset (Start Fresh if Needed)
 
 If you need to completely reset your database and start fresh:
@@ -105,7 +124,7 @@ If you need to completely reset your database and start fresh:
 3. **Restart Services**:
 
    ```bash
-   docker-compose up -d
+   docker-compose --profile full up -d
    ```
 
 4. **Reconfigure**:
@@ -116,6 +135,41 @@ The reset script safely removes all tables, functions, triggers, and policies wi
 
 </details>
 
+## 🛠️ Installing Make
+
+Make is required for the development workflow. Installation varies by platform:
+
+### Windows
+
+```bash
+# Option 1: Using Chocolatey
+choco install make
+
+# Option 2: Using Scoop
+scoop install make
+
+# Option 3: Using WSL2
+wsl --install
+# Then in WSL: sudo apt-get install make
+```
+
+### macOS
+
+```bash
+# Make comes pre-installed on macOS
+# If needed: brew install make
+```
+
+### Linux
+
+```bash
+# Debian/Ubuntu
+sudo apt-get install make
+
+# RHEL/CentOS/Fedora
+sudo yum install make
+```
+
 ## ⚡ Quick Test
 
 Once everything is running:
@@ -221,11 +275,11 @@ Archon uses true microservices architecture with clear separation of concerns:
 
 By default, Archon services run on the following ports:
 
-- **Archon-UI**: 3737
-- **Archon-Server**: 8181
-- **Archon-MCP**: 8051
-- **Archon-Agents**: 8052
-- **Archon-Docs**: 3838 (optional)
+- **archon-ui**: 3737
+- **archon-server**: 8181
+- **archon-mcp**: 8051
+- **archon-agents**: 8052
+- **archon-docs**: 3838 (optional)
 
 ### Changing Ports
 
@@ -269,27 +323,136 @@ This is useful when:
 
 After changing hostname or ports:
 
-1. Restart Docker containers: `docker-compose down && docker-compose up -d`
+1. Restart Docker containers: `docker-compose down && docker-compose --profile full up -d`
 2. Access the UI at: `http://${HOST}:${ARCHON_UI_PORT}`
 3. Update your AI client configuration with the new hostname and MCP port
 
 ## 🔧 Development
 
-For development with hot reload:
+### Quick Start
+
+```bash
+# Install dependencies
+make install
+
+# Start development (recommended)
+make dev        # Backend in Docker, frontend local with hot reload
+
+# Alternative: Everything in Docker
+make dev-docker # All services in Docker
+
+# Stop everything (local FE needs to be stopped manually)
+make stop
+```
+
+### Development Modes
+
+#### Hybrid Mode (Recommended) - `make dev`
+
+Best for active development with instant frontend updates:
+
+- Backend services run in Docker (isolated, consistent)
+- Frontend runs locally with hot module replacement
+- Instant UI updates without Docker rebuilds
+
+#### Full Docker Mode - `make dev-docker`
+
+For all services in Docker environment:
+
+- All services run in Docker containers
+- Better for integration testing
+- Slower frontend updates
+
+### Testing & Code Quality
 
 ```bash
-# Backend services (with auto-reload)
-docker-compose up archon-server archon-mcp archon-agents --build
+# Run tests
+make test       # Run all tests
+
+# Run linters
+make lint       # Lint all code
 
-# Frontend (with hot reload)
-cd archon-ui-main && npm run dev
+# Check environment
+make check      # Verify environment setup
 
-# Documentation (with hot reload)
-cd docs && npm start
+# Clean up
+make clean      # Remove containers and volumes (asks for confirmation)
+```
+
+### Viewing Logs
+
+```bash
+# View logs using Docker Compose directly
+docker-compose logs -f              # All services
+docker-compose logs -f archon-server # API server
+docker-compose logs -f archon-mcp    # MCP server
+docker-compose logs -f archon-ui     # Frontend
 ```
 
 **Note**: The backend services are configured with `--reload` flag in their uvicorn commands and have source code mounted as volumes for automatic hot reloading when you make changes.
 
+## 🔍 Troubleshooting
+
+### Common Issues and Solutions
+
+#### Port Conflicts
+
+If you see "Port already in use" errors:
+
+```bash
+# Check what's using a port (e.g., 3737)
+lsof -i :3737
+
+# Stop all containers and local services
+make stop
+
+# Change the port in .env
+```
+
+#### Docker Permission Issues (Linux)
+
+If you encounter permission errors with Docker:
+
+```bash
+# Add your user to the docker group
+sudo usermod -aG docker $USER
+
+# Log out and back in, or run
+newgrp docker
+```
+
+#### Windows-Specific Issues
+
+- **Make not found**: Install Make via Chocolatey, Scoop, or WSL2 (see [Installing Make](#installing-make))
+- **Line ending issues**: Configure Git to use LF endings:
+  ```bash
+  git config --global core.autocrlf false
+  ```
+
+#### Frontend Can't Connect to Backend
+
+- Check backend is running: `curl http://localhost:8181/health`
+- Verify port configuration in `.env`
+- For custom ports, ensure both `ARCHON_SERVER_PORT` and `VITE_ARCHON_SERVER_PORT` are set
+
+#### Docker Compose Hangs
+
+If `docker-compose` commands hang:
+
+```bash
+# Reset Docker Compose
+docker-compose down --remove-orphans
+docker system prune -f
+
+# Restart Docker Desktop (if applicable)
+```
+
+#### Hot Reload Not Working
+
+- **Frontend**: Ensure you're running in hybrid mode (`make dev`) for best HMR experience
+- **Backend**: Check that volumes are mounted correctly in `docker-compose.yml`
+- **File permissions**: On some systems, mounted volumes may have permission issues
+
 ## 📈 Progress
 
 <p align="center">

archon-ui-main/Dockerfile

@@ -18,8 +18,8 @@ RUN mkdir -p /app/coverage && chmod 777 /app/coverage
 # Copy source code
 COPY . .
 
-# Expose Vite's default port
-EXPOSE 5173
+# Expose the port configured in package.json (3737)
+EXPOSE 3737
 
-# Start Vite dev server with host binding for Docker
-CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0"]
+# Start Vite dev server (already configured with --port 3737 --host in package.json)
+CMD ["npm", "run", "dev"]

archon-ui-main/src/components/BackendStartupError.tsx

@@ -28,12 +28,12 @@ export const BackendStartupError: React.FC = () => {
                   <span className="font-semibold">Check Docker Logs</span>
                 </div>
                 <p className="text-red-100 font-mono text-sm mb-3">
-                  Check the <span className="text-red-400 font-bold">Archon-Server</span> logs in Docker Desktop for detailed error information.
+                  Check the <span className="text-red-400 font-bold">Archon API server</span> container logs in Docker Desktop for detailed error information.
                 </p>
                 <div className="space-y-2 text-xs text-red-300">
                   <p>1. Open Docker Desktop</p>
                   <p>2. Go to Containers tab</p>
-                  <p>3. Click on <span className="text-red-400 font-semibold">Archon-Server</span></p>
+                  <p>3. Look for the Archon server container (typically named <span className="text-red-400 font-semibold">archon-server</span> or similar)</p>
                   <p>4. View the logs for the specific error message</p>
                 </div>
               </div>