Restructured backend with appropriate tests

Signed-off-by: anuunchin <anuun.ch@gmail.com>

Author: anuunchin

.github/workflows/ci.yml

@@ -104,11 +104,11 @@ jobs:
       - name: Install dependencies
         run: make install-backend
 
-      # use py_compile instead of running main.py
-      # because main.py contains a web server that runs forever
-      - name: Build (syntax check)
+      - name: Build (import check)
         working-directory: src/backend
-        run: uv run python -m py_compile main.py
+        run: |
+          uv run python -c "import webcam.main"
+          uv run python -c "import analyzer.main"
 
   # Test stage
 

.github/workflows/dco.yml

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: 2025 robot-visual-perception
+#
+# SPDX-License-Identifier: MIT
+
+name: DCO Check
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  check-signoff:
+    name: Check commit sign-off
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Get PR commits
+        id: get_commits
+        uses: tim-actions/get-pr-commits@v1.1.0
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: DCO check
+        uses: tim-actions/dco@v1.1.0
+        with:
+          commits: ${{ steps.get_commits.outputs.commits }}

Makefile

@@ -101,21 +101,36 @@ test-frontend:
 	cd src/frontend && npm test
 
 test-backend:
-	cd src/backend && uv run pytest
+	cd src/backend && uv run pytest -s
 
-run-backend-local:
-	cd src/backend && uv run uvicorn webrtc.server:app --host 0.0.0.0 --port 8000
+run-webcam-local:
+	@echo "Starting webcam service on port 8000..."
+	cd src/backend && uv run uvicorn webcam.main:app --host 0.0.0.0 --port 8000 --reload
+
+run-analyzer-local:
+	@echo "Starting analyzer service on port 8001..."
+	cd src/backend && uv run uvicorn analyzer.main:app --host 0.0.0.0 --port 8001 --reload
+
+run-backend-local: run-webcam-local
+	@echo "Note: To run analyzer, use 'make run-analyzer-local' in another terminal"
 
 run-frontend-local:
-	cd src/frontend && VITE_BACKEND_URL=http://localhost:8000 npm run dev
+	cd src/frontend && VITE_BACKEND_URL=http://localhost:8001 npm run dev
 
 docker-build: docker-build-frontend docker-build-backend
 
 docker-build-frontend:
-	docker build -t robot-frontend:latest src/frontend
+	docker build \
+		--build-arg VITE_BACKEND_URL=http://host.docker.internal:8001 \
+		-t robot-frontend:latest src/frontend
+
+docker-build-backend: docker-build-webcam docker-build-analyzer
+
+docker-build-webcam:
+	docker build -f src/backend/Dockerfile.webcam -t robot-webcam:latest src/backend
 
-docker-build-backend:
-	docker build -t robot-backend:latest src/backend
+docker-build-analyzer:
+	docker build -f src/backend/Dockerfile.analyzer -t robot-analyzer:latest src/backend
 
 docker-run-frontend:
 	@echo "Starting frontend container..."
@@ -125,17 +140,25 @@ docker-run-frontend:
 	@open http://localhost:8080 || echo "Please open http://localhost:8080 in your browser"
 	@echo "To stop: docker stop robot-frontend-dev"
 
-docker-run-backend:
-	@echo "Starting backend container..."
-	@docker run -d --rm -p 8000:8000 --name robot-backend-dev robot-backend:latest
+docker-run-backend: docker-run-webcam
+
+docker-run-webcam:
+	@echo "Starting webcam service container..."
+	@docker run -d --rm -p 8000:8000 --name robot-webcam-dev robot-webcam:latest
+	@sleep 1
+	@echo "Webcam service running at http://localhost:8000"
+	@echo "To stop: docker stop robot-webcam-dev"
+
+docker-run-analyzer:
+	@echo "Starting analyzer service container..."
+	@docker run -d --rm -p 8001:8001 --env WEBCAM_OFFER_URL=http://host.docker.internal:8000/offer --name robot-analyzer-dev robot-analyzer:latest
 	@sleep 1
-	@echo "Opening browser at http://localhost:8000"
-	@open http://localhost:8000 || echo "Please open http://localhost:8000 in your browser"
-	@echo "To stop: docker stop robot-backend-dev"
+	@echo "Analyzer service running at http://localhost:8001"
+	@echo "To stop: docker stop robot-analyzer-dev"
 
 docker-stop:
-	@docker stop robot-frontend-dev robot-backend-dev 2>/dev/null || true
+	@docker stop robot-frontend-dev robot-webcam-dev robot-analyzer-dev 2>/dev/null || true
 
 docker-clean: docker-stop
-	@docker rmi robot-frontend:latest robot-backend:latest || true
+	@docker rmi robot-frontend:latest robot-webcam:latest robot-analyzer:latest || true
 

README.md

@@ -16,23 +16,20 @@ Minimal real-time object and distance detection via YOLO on a WebRTC video strea
 - React + Vite frontend showing the remote stream and detection stats
 
 ## Run backend (WebRTC)
-Prereqs: Python 3.11+
+Prereqs: Python 3.11
 
-1) Install dependencies (Mac)
+1) Install dependencies
 ```
-cd src/backend
-python3 -m venv venv
-source venv/bin/activate
-pip3 install -r requirements.txt
+make dev
 ```
 
 2) Start the webcam service
 ```
-uv run uvicorn server:app --host 0.0.0.0 --port 8000
+make run-webcam-local
 ```
 3) Start the analyzer service (separate terminal)
 ```
-uv run uvicorn analyzer:app --host 0.0.0.0 --port 8001
+make run-analyzer-local
 ```
 The first analyzer start will download `yolov8n.pt` automatically (this will take some time)
 
@@ -41,21 +38,25 @@ Optional environment variables (more relevant later):
 - `CAMERA_HFOV_DEG` (default 60) – horizontal field of view used for distance estimate
 - `OBJ_WIDTH_M` (default 0.5) – nominal object width used in distance estimate
 
+> Check `src/backend/common/config.py`.
+
 ## Run frontend
-Prereqs: Node 18+.
+Prereqs: Node 20.
 
 1) Install deps
 ```
-cd src/frontend
-npm install
+make dev
 ```
+> `make dev` installs both frontend and backend.
 
 2) Start dev server
 ```
-VITE_BACKEND_URL=http://localhost:8001 npm run dev
+make run-frontend-local
 ```
 Open the shown URL in your console.
 
 ## Notes
 - The webcam service mirrors and streams raw frames only; the analyzer handles YOLO inference and overlays.
 - Analyzer inference is throttled to ~10 Hz to keep latency low.
+
+> IMPORTANT: Please read the `CONTRIBUTING.md`.

src/backend/Dockerfile

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2025 robot-visual-perception
+#
+# SPDX-License-Identifier: MIT
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies for opencv
+RUN apt-get update && apt-get install -y \
+    libgl1 \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY common/ ./common/
+COPY analyzer/ ./analyzer/
+COPY models/ ./models/
+
+EXPOSE 8001
+
+CMD ["uvicorn", "analyzer.main:app", "--host", "0.0.0.0", "--port", "8001"]
+

src/backend/Dockerfile.analyzer

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2025 robot-visual-perception
+#
+# SPDX-License-Identifier: MIT
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies for opencv
+RUN apt-get update && apt-get install -y \
+    libgl1 \
+    libglib2.0-0 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY common/ ./common/
+COPY webcam/ ./webcam/
+COPY models/ ./models/
+
+EXPOSE 8000
+
+CMD ["uvicorn", "webcam.main:app", "--host", "0.0.0.0", "--port", "8000"]
+