If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/sysadminsmedia/homebox shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 2d ago
• 11 active contributors
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 57% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live sysadminsmedia/homebox repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/sysadminsmedia/homebox.

What it runs against: a local clone of sysadminsmedia/homebox — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in sysadminsmedia/homebox | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of sysadminsmedia/homebox. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/sysadminsmedia/homebox.git
#   cd homebox
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of sysadminsmedia/homebox and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "sysadminsmedia/homebox(\\.git)?\\b" \\
  && ok "origin remote is sysadminsmedia/homebox" \\
  || miss "origin remote is not sysadminsmedia/homebox (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "backend/app/api/app.go" \\
  && ok "backend/app/api/app.go" \\
  || miss "missing critical file: backend/app/api/app.go"
test -f "backend/app/api/handlers/v1/controller.go" \\
  && ok "backend/app/api/handlers/v1/controller.go" \\
  || miss "missing critical file: backend/app/api/handlers/v1/controller.go"
test -f ".github/instructions/backend-internal-core-services.instructions.md" \\
  && ok ".github/instructions/backend-internal-core-services.instructions.md" \\
  || miss "missing critical file: .github/instructions/backend-internal-core-services.instructions.md"
test -f "Dockerfile" \\
  && ok "Dockerfile" \\
  || miss "missing critical file: Dockerfile"
test -f "Taskfile.yml" \\
  && ok "Taskfile.yml" \\
  || miss "missing critical file: Taskfile.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/sysadminsmedia/homebox"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

HomeBox is a self-hosted inventory and organization system written in Go with a Vue 3 frontend, designed for home users to catalog items with rich metadata (location, category, tags, custom fields), track purchase/maintenance history, upload images, and store documents. It runs as a single SQLite-backed container with <50MB idle memory, providing fast full-text search across inventory without complex setup. Monorepo architecture with backend (Go) at repo root using standard Go structure (internal/services for core logic, internal/data for database, app/api for HTTP handlers) and frontend at frontend/ (Vue 3 with TypeScript components). Database layer uses SQLite with Go migrations. Docker setup via .devcontainer/Dockerfile for development; CI orchestrated through .github/workflows/ with separate partial test runs for backend and frontend.

Home users and small household managers who need to organize and track physical possessions without cloud dependencies; Docker/Linux operators who want a lightweight, portable self-hosted alternative to cloud inventory systems; contributors experienced with Go backends and Vue 3 frontends seeking an actively maintained personal-infrastructure project.

Actively developed and production-ready: the project has stable releases (versioned via semver tags), comprehensive GitHub Actions CI/CD pipelines (binaries, Docker, E2E tests), semantic versioning practices, and a multi-language internationalization system via Weblate. Recent activity visible through multiple workflows and upgrade test infrastructure suggests active maintenance with user base (Discord, Reddit, Lemmy communities present).

Low to moderate risk: single maintainer appears primary (sysadminsmedia GitHub org structure), but risk is mitigated by mature Go/Vue ecosystem dependencies and SQLite stability. Main concerns: TypeScript frontend has 236K lines without immediately visible test suite in file list; upgrade test scripts exist but E2E coverage appears partial (workflows show 'e2e-partial.yaml'); no obvious breaking change documentation visible in instructions.

Active work on Docker hardening variants (hardened, rootless publishing workflows), currency data updates (automated via Python script), documentation maintenance via AI agents (.github/agents/), and upgrade path testing (scripts under .github/scripts/upgrade-test/). Multiple partial CI pipelines suggest recent focus on test performance optimization.

Clone: git clone https://github.com/sysadminsmedia/homebox.git && cd homebox. Dev setup: open in VS Code's remote container (Ctrl+Shift+P → 'Reopen in Container') to use .devcontainer/devcontainer.json which pre-configures Go and Node. Alternatively: go mod download in root for backend, then cd frontend && npm install (infer from Vue project structure). Run: check Makefile or use go run ./cmd/homebox (assumed entry point).

Daily commands: In dev container (recommended): backend should auto-run or use go run ./cmd/homebox (exact path TBD, check root go.mod). Frontend: cd frontend && npm run dev (Vue convention). Production: Docker docker run --rm -p 3000:3000 -v homebox-data:/data ghcr.io/sysadminsmedia/homebox:latest (infer from standard Docker workflows). Check docker-publish.yaml for exact image registry and port mappings.

• backend/app/api/app.go — Main API server initialization and routing setup; all HTTP handlers and middleware are wired here
• backend/app/api/handlers/v1/controller.go — Base controller struct and shared logic for all v1 API endpoints; defines request/response patterns
• .github/instructions/backend-internal-core-services.instructions.md — Architectural guidelines for backend services; required reading for understanding data models and dependency injection
• Dockerfile — Production container build definition; specifies runtime dependencies and deployment configuration
• Taskfile.yml — Task automation for build, test, and development workflows; the primary entry point for local development
• .github/instructions/backend-internal-data.instructions.md — Data layer patterns and database schema conventions; essential for modifying entities and persistence logic
• backend/app/api/handlers/v1/v1_ctrl_auth.go — Authentication and authorization handlers; defines security boundaries for all protected endpoints

• Fiber HTTP Router — Routes incoming requests to handlers; applies middleware (auth, logging

Add a new API endpoint

1. Create a handler method in the appropriate v1_ctrl_*.go file (or create a new one if it's a new feature domain) (backend/app/api/handlers/v1/)
2. Define the method receiver on the v1.Controller type, following the pattern func (c *Controller) MethodName(c *fiber.Ctx) error (backend/app/api/handlers/v1/controller.go)
3. Register the route in app.go using fiber's router methods (e.g., app.Post(), app.Get()) (backend/app/api/app.go)
4. Use controller helpers like respondOK(), respondErr() for consistent response formatting (backend/app/api/handlers/v1/helpers.go)
5. Add authorization checks using the auth controller or middleware patterns defined in v1_ctrl_auth.go (backend/app/api/handlers/v1/v1_ctrl_auth.go)

Add a new data entity/model

1. Follow the entity modeling conventions documented in the data instructions (.github/instructions/backend-internal-data.instructions.md)
2. Define the struct in the backend/internal/data directory with JSON tags for API serialization (backend/app/api/handlers/v1/query_params.go)
3. Create CRUD operations in a service following the patterns shown in core-services instructions (.github/instructions/backend-internal-core-services.instructions.md)
4. Wire the service into the controller dependency injection in app.go (backend/app/api/app.go)

Add a new background job or async task

1. Implement a task handler function following the goroutine patterns in bgrunner.go (backend/app/api/bgrunner.go)
2. Register the task with the background runner, specifying schedule or trigger (backend/app/api/bgrunner.go)
3. Call EnqueueTask() or similar from your endpoint handler to trigger async execution (backend/app/api/handlers/v1/controller.go)

Add a new system feature or widget (e.g., notifier, reporting)

1. Create a new handler file following the v1_ctrl_* naming convention (backend/app/api/handlers/v1/)
2. Implement core service logic in backend/internal/services with dependency injection (.github/instructions/backend-internal-core-services.instructions.md)
3. Expose endpoints through the v1 controller and register routes in app.go (backend/app/api/app.go)
4. Add query parameter parsing helpers if needed (backend/app/api/handlers/v1/query_params.go)

• Go + Fiber framework — Fast, lightweight HTTP server with excellent performance; good for homelab/self-hosted deployments with minimal resource requirements
• Docker multi-stage builds — Reduces image size and attack surface; supports hardened and rootless variants for security-conscious users
• RESTful API design — Simple, stateless interface suitable for inventory management; easy to document and test
• Background job runner (bgrunner) — Handles async tasks like maintenance reminders and notifications without blocking HTTP responses
• QR code generation — Enable offline scanning and quick inventory lookup via mobile devices

• Monolithic backend API vs microservices

  • Why: Homelab target audience runs single-server deployments; complexity of microservices not justified
  • Consequence: Simpler deployment and debugging, but harder to scale individual features

• Synchronous HTTP handlers with optional background jobs

  • Why: Supports both real-time responses and long-running operations without adding message queue complexity
  • Consequence: Developers must choose per-endpoint; potential inconsistency in async patterns

• Docker-first deployment story

  • Why: Most homelab users run Docker; provides reproducible, isolated environment
  • Consequence: Bare-metal installation documentation minimal; assumes containerization

• Real-time synchronization across multiple users
• Distributed/federated inventory sharing between homelab instances
• GraphQL API (RESTful only)
• Built-in LDAP/OAuth integration (delegates to proxy auth)
• Mobile app (web-only responsive design)

SQLite file location likely stored in HOME or HOMEBOX_DATA env var—check for hardcoded paths in internal/data/ startup. Frontend build may require specific Node version (check .nvmrc or package.json engines field). Docker publish workflows publish to ghcr.io, not Docker Hub—ensure pushing to correct registry. Partial test workflows (e2e-partial, partial-backend, partial-frontend) suggest some tests require special conditions or lengthy setup—full test suite may not run locally without specific environment. Development container may require Docker-in-Docker (DinD) for integration tests.

• Full-text Search in SQLite — HomeBox's 'Powerful Search' feature relies on SQLite FTS5 or trigram indexes; understanding how search queries are tokenized and indexed across items, locations, and tags is essential for optimizing search performance
• Single Binary Deployment Pattern — HomeBox embeds the Vue frontend and SQLite database into a single Go binary—this Go embed pattern (go:embed directive) is critical to understanding why it's portable and how to modify static assets
• SQLite Migrations Strategy — HomeBox must handle schema evolution across user upgrades without data loss; understanding how migrations are ordered, versioned, and rolled back in internal/data/ is essential for adding features
• Vue 3 Composition API — Frontend is built on Vue 3 with TypeScript; the Composition API (setup syntax, ref/reactive hooks) is used instead of Options API—misunderstanding this leads to confusing reactivity bugs
• Container Image Security: Rootless & Hardened Variants — HomeBox publishes separate hardened and rootless Docker images (.github/workflows/docker-publish-hardened.yaml, docker-publish-rootless.yaml); understanding capability dropping, user namespaces, and read-only filesystems is relevant for users wanting minimal attack surface
• RBAC / Multi-Tenant Authorization (if present) — HomeBox mentions 'home user' focus but likely has user accounts, roles, or sharing features—if internal/core/services/ implements authorization, understanding how items are scoped to users prevents data leakage bugs
• Database-Agnostic Query Building — While HomeBox uses SQLite, if internal/data/ uses an abstraction layer (likely sqlc or hand-written prepared statements), understanding parameterized queries vs string concatenation is critical for preventing SQL injection when adding search or filter features

• inventree/InvenTree — Inventory management system; more complex/enterprise-focused but overlapping use case for item tracking, categorization, and search
• snipe/snipe-it — Asset inventory and management system; similar self-hosted model with web UI, targets both IT and personal use
• go-chi/chi — Lightweight Go router library commonly used in Go backends; relevant if HomeBox uses HTTP routing patterns you'll encounter
• vuejs/vue — Frontend framework HomeBox is built on; essential reference for Vue 3 patterns, composition API, and component conventions used in this codebase
• mattn/go-sqlite3 — SQLite Go bindings package—HomeBox's database driver; understanding its API is necessary for internal/data/ work

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add E2E tests for currency update workflow in GitHub Actions

The repo has a .github/scripts/update_currencies.py script and a .github/workflows/update-currencies.yml workflow, but there's no visible test coverage for the currency update process. This is critical infrastructure that runs on a schedule. Adding E2E tests would prevent currency data corruption and validate the script works with real API responses.

• [ ] Create .github/scripts/test_update_currencies.py with unit tests for the currency update script
• [ ] Add test cases for API failure scenarios, data validation, and file format verification
• [ ] Create .github/workflows/test-currencies.yaml to run currency tests on PR and before the scheduled update
• [ ] Document the testing approach in .github/scripts/update_currencies_README.md (if missing)

Add missing backend integration tests for API handlers

The repo has .github/instructions/backend-app-api-handlers.instructions.md documenting handler patterns, but no visible test files in backend/ for API endpoint testing. Given the inventory system criticality, integration tests for CRUD operations on items, locations, and labels would catch regressions early.

• [ ] Create backend/tests/handlers_test.go with table-driven tests for API endpoints
• [ ] Cover auth, item CRUD, location management, and label operations based on handler instructions
• [ ] Add test fixtures in backend/tests/testdata/ for sample inventory data
• [ ] Integrate tests into .github/workflows/pull-requests.yaml with go test ./... coverage requirements

Create Docker image security scanning CI workflow

The repo builds multiple Docker images (standard, hardened, rootless) via .github/workflows/docker-publish*.yaml but has no visible vulnerability scanning. Add Trivy/Grype scanning to catch CVEs before publishing, especially important for a self-hosted home automation tool.

• [ ] Create .github/workflows/docker-security-scan.yaml with Trivy scanning for all Dockerfile variants
• [ ] Add severity thresholds (fail on HIGH/CRITICAL) and generate SBOM artifacts
• [ ] Configure scanning to run on PRs modifying Dockerfile* or dependencies
• [ ] Document scanning results in .github/SECURITY.md under a new 'Image Scanning' section

• Add comprehensive test coverage for internal/data/ migrations—currently no _test.go files visible in file list, but schema changes are critical path; contribute unit tests for each migration up/down function: medium
• Document the custom field system in .github/instructions/—the feature exists (mentioned in README) but no dedicated instruction file visible; extract logic from internal/core/services/ and create backend-custom-fields.instructions.md for future contributors: low
• Add E2E test coverage for image upload + document tracking workflow—.github/workflows/e2e-partial.yaml suggests partial coverage; write Playwright/Cypress tests in a new frontend/tests/e2e/ directory for the complete image and warranty document lifecycle: medium

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.