The Problem

Manual inventory in Homebox is tedious: users must create items one‑by‑one, attach photos, and keep metadata up to date. When onboarding a new room or collection this becomes a bottleneck, especially for non‑technical staff who lack a fast data‑entry workflow.

What This Does

Homebox Companion captures photos, runs them through an LLM‑backed vision model, and auto‑generates Homebox items. The UI lives in frontend/ (Svelte + Tailwind) and talks to a Python API in server/. Core logic for AI prompts lives in src/homebox_companion/ai/ and the chat interface that can query or modify the inventory is in src/homebox_companion/chat/.

Key files:

  • frontend/src/lib/api/index.ts – aggregates all client‑side API calls.
  • frontend/src/lib/components/… – UI panels (e.g., AiCorrectionPanel.svelte, ItemCustomFields.svelte).
  • server/app.py – FastAPI entry point that mounts the routers under server/api/.
  • src/homebox_companion/core/config.py – reads environment variables (HBC_LLM_API_KEY, HBC_HOMEBOX_URL).

The repo also supplies Docker assets (Dockerfile, docker‑compose.yml) for a one‑command deployment.

How It Is Wired

Execution starts with server/app.py. FastAPI creates an app object and includes routers from server/api/__init__.py. The most‑used router is server/api/items.py, which calls src/homebox_companion/homebox/client.py to talk to the downstream Homebox REST API.

When a user uploads a photo via the Svelte UI, the frontend calls frontend/src/lib/api/vision.ts → frontend/src/lib/api/client.ts → the /vision endpoint (server/api/vision.py). That endpoint forwards the image to src/homebox_companion/ai/images.py, which uses LiteLLM (src/homebox_companion/ai/llm.py) to invoke OpenAI GPT‑5. The response is parsed by src/homebox_companion/ai/response_models.py and returned to the UI for review.

The chat feature follows a similar path: UI frontend/src/lib/api/chat.ts → /chat router (server/api/chat.py) → src/homebox_companion/chat/orchestrator.py → LLM client (src/homebox_companion/chat/llm_client.py).

Blast‑radius hubs

  • server/dependencies.py is imported by 15 modules; any change here ripples widely.
  • frontend/src/lib/api/client.ts sits in a circular import with several Svelte stores, increasing maintenance risk.

Complexity hotspots

  • Deep nesting (max depth 7) in src/homebox_companion/chat/session.py, frontend/src/lib/api/chat.ts, and workflow scripts, making later modifications error‑prone.
  • src/homebox_companion/homebox/client.py and src/homebox_companion/mcp/tools.py each exceed 1 000 lines, suggesting they should be split.
  • Repeated 6‑line UI snippets appear in > 20 Svelte components, indicating a DRY opportunity.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/homebox-companion
cd homebox-companion

# Copy example env and fill in your keys
cp .env.example .env
# edit .env → set HBC_LLM_API_KEY and HBC_HOMEBOX_URL

# Build and run the stack
docker compose up -d   # uses Dockerfile and docker-compose.yml

The container exposes port 8000. Open http://localhost:8000 and log in with your Homebox credentials (or the demo demo@example.com / demo). The frontend is served by the same container; no separate npm install is required for the default Docker build, but for local UI development you can run:

cd frontend
npm ci               # lockfile present
npm run dev          # vite dev server (see vite.config.ts)

Real‑World Use

A facilities manager rolls out a new office. They start the companion, scan the office QR code, take a batch of photos with a tablet, and let the AI propose items. Minor corrections are made in the review screen, then a single “Submit” pushes all items to Homebox, creating a searchable inventory without manual entry.

Code Health & Issues

  • High – CI does not run the test suite (.github/workflows/* lacks a test step).
  • Medium – No dependency‑vulnerability scan in CI.
  • Low – Workflow jobs lack timeout-minutes.
  • Low – Missing convention files (.editorconfig, .gitattributes, formatter config).

Additional static findings: 15 import cycles (e.g., frontend/src/lib/api/client.ts), deep nesting in 33 places, broad exception catches in several AI and Homebox client modules, and duplicated UI code across many Svelte components.

The Bottom Line

Homebox Companion delivers a functional AI‑driven inventory pipeline with a clean Docker‑first deployment, but the codebase contains several maintainability hotspots (circular imports, oversized modules) and CI gaps that should be addressed before scaling. It is suitable for teams comfortable with Python/FastAPI and Svelte who need rapid item capture, provided they allocate time for refactoring and CI hardening.