[DEVOPS] Docker Compose "Simulacrum" Dev Environment (#152)

[scottchronicity]

Context

Not everyone has a Jetson. We need a docker-compose.dev.yml that spins up the entire Orpheus stack — Mosquitto broker, SQLite database, FastAPI backend, React UI, and mock agents that replay pre-recorded audio/video events from artifacts/audio-samples/.

A new contributor should go from git clone to a working, interactive system in under 5 minutes.

Architecturally Significant Requirements (ASRs)

Interface (Contract):

• docker-compose.dev.yml at the repo root defining all services.
• Makefile targets: make dev-up, make dev-down, make dev-logs, make dev-status.
• Mock agent configuration: docker/mock-agents/config.yaml specifying replay files and intervals.
• Service naming convention: orpheus-<component> (e.g., orpheus-broker, orpheus-api, orpheus-ui).

Implementation (Internal Logic):

• Multi-stage Dockerfiles for Python agents (builder + runtime).
• Mock agent: Python script replaying audio samples from mounted artifacts/ volume.
• Hot-reload: local src/ directories mounted as volumes for FastAPI (uvicorn --reload) and React (Vite HMR).
• Health checks: each service has a Docker HEALTHCHECK with appropriate interval.

Architectural Constraints

• Must run seamlessly on macOS (ARM and x86) and Linux (ARM and x86).
• Must mount local directories for hot-reloading (UI and backend code changes reflected immediately).
• Mock agents must be clearly labeled in the UI so users don't confuse simulated data with real detections.
• Must not require any API keys, cloud services, or external dependencies.
• Docker images must be multi-arch (buildx with linux/amd64,linux/arm64).

Acceptance Criteria

Feature: Docker Compose Simulacrum Dev Environment

  Scenario: New contributor quick start
    Given a fresh clone of the Orpheus repository
    When the contributor runs "make dev-up"
    Then all services start within 5 minutes
    And the React UI is accessible at http://localhost:3000
    And mock detection events appear in the dashboard

  Scenario: Hot reload backend code
    Given the dev environment is running
    When a developer modifies a FastAPI endpoint
    Then the change is reflected without restarting containers

  Scenario: Mock agents clearly labeled
    Given mock agents are replaying sample data
    When viewing detections in the dashboard
    Then each mock detection is tagged with source "simulacrum"

Definition of Done

• docker-compose.dev.yml added to the repository root.
• Mock agent script(s) that replay audio samples and generate synthetic video events.
• make dev-up and make dev-down targets in the root Makefile.
• Documented in CONTRIBUTING.md with a "Quick Start" section.