The Problem

HomeBox is an inventory and organization system for home users, built with a Go backend and Vue/TypeScript frontend. The repository contains 893 files across a monorepo structure with distinct backend (336 files) and frontend (428 files) projects. The codebase shows measurable structural concerns that impact maintainability and deployment reliability, particularly around test integration, dependency management, and circular dependencies.

What This Does

HomeBox provides rich organization of items into categories, locations, and tags with powerful search, image upload, document/warranty tracking, and purchase/maintenance tracking. The backend (Go) handles API routes, database operations via Ent ORM, and service layer logic, while the frontend (Vue 257 files, TypeScript 123 files) provides the user interface. The repository uses pnpm for package management, Docker for containerization, and GitLab CI for continuous integration. Key entry points include backend/app/api/main.go:94 which reaches 324 functions, and backend/internal/core/services/main_test.go:32 which reaches 250 functions. The system reads/writes files and a database, with 19 functions performing database operations and 15 performing file operations.

How It Is Wired

Execution starts at backend/app/api/main.go:94 (entry point main), which reaches 324 functions and is called by nothing else in the repo. The call graph shows Entity is called from 303 places, EntityTemplate from 189, and User from 146, indicating these are the most widely used types. The internal call graph has 4614 resolved call edges between functions.

A significant issue: the frontend module frontend/lib/api/base/index.ts participates in a circular import with frontend/lib/api/base/base-api.ts, creating an instability of 0.11. This cycle must be broken by extracting shared types, inverting a dependency, or deferring an import.

Code health concerns include 16 oversized files (notably frontend/lib/api/types/data-contracts.ts at 1066 lines, backend/app/api/static/docs/docs.go, and backend/internal/data/ent/client.go), 38 instances of deep nesting (max indentation depth 11), and 1313 repeated 6-line blocks across 259 files indicating duplicated logic in handler files. The import graph contains 128 internal modules with 90 edges and 2 modules in circular dependencies.

Database access flows through backend/internal/data/ent/client.go which defines NewClient, init, newConfig, options, and Debug. This file is called from 32 other files, calls into 14, and reads/writes both files and the database. The Ent schema defines entities for items, entities, templates, groups, attachments, authroles, authtokens, and fields with corresponding where/query/create/update generators.

How To Use It

Setup: Clone the repository: git clone https://github.com/moses-y/homebox. The project uses pnpm as package manager (frontend/package.json, docs/package.json) and Go modules (backend/go.mod). Docker is used for deployment with multiple Dockerfiles (Dockerfile, Dockerfile.hardened, Dockerfile.rootless). Data directory must have correct permissions for rootless/hardened images: mkdir -p /path/to/data/folder && chown 65532:65532 -R /path/to/data/folder.

Configuration: Environment variables are required for TZ (timezone). The README demonstrates Docker Compose usage with --env TZ=Europe/Bucharest and volume mounting for data persistence. The .devcontainer/Dockerfile uses mcr.microsoft.com/vscode/devcontainers/typescript-node:22-bullseye as base image.

Running it: Start via Docker: docker run -d --name homebox --restart unless-stopped --publish 3100:7745 --env TZ=Europe/Bucharest --volume /path/to/data/folder/:/data ghcr.io/sysadminsmedia/homebox:latest. For development, the .devcontainer/devcontainer.json likely configures the development environment.

Real-World Use

A home user organizes household items—tools, electronics, furniture—with purchase dates, prices, maintenance schedules, and associated documents/warranties. Images of items are uploaded for visual identification. Search enables quick location of items by category, tag, or custom fields. The system runs as a lightweight container (idle memory <50MB) and can be deployed on any host with Docker, with SQLite providing local data persistence. Admins can track maintenance cycles and warranty expirations across a household inventory.

Code Health & Issues

  • HIGH: Make CI invoke the test suite it has - .github/workflows contain 52 test files but no test command in the 4 workflows read; a green check that never executes assertions is worse than no check.
  • MEDIUM: Enable Dependabot or Renovate - 4 manifest files (go.mod, package.json, etc.) have no update bot configured; without a bot, published advisories sit unpatched.
  • MEDIUM: Pin the container base image by digest - .devcontainer/Dockerfile uses mcr.microsoft.com/vscode/devcontainers/typescript-node:22-bullseye without a digest, meaning today's build and last month's contain different libc and a different CVE set with no record.
  • MEDIUM: Gate pull requests on a dependency vulnerability scan - no dependency scan exists in CI; this is the one gate that would catch a known-vulnerable package before it reaches a build.
  • MEDIUM: Move large binaries to Git LFS or out of the repository - backend/pkgs/labelmaker/testdata/NotoSansKR-VF.ttf is 9.9MB; one repository in the sample carries twenty blobs over 5MB including a 10.9MB spreadsheet.
  • MEDIUM: Set persist-credentials: false on checkout - .github/workflows/binaries-publish.yaml has checkout keeping the token; dependencies are installed with the token still in .git/config.
  • LOW: Set timeout-minutes on the workflow jobs - 4 workflow(s) declare no job timeout; a wedged step runs to the six-hour platform default.

The Bottom Line

HomeBox is a functional inventory management system with a Go backend and Vue frontend, deployed via Docker with SQLite persistence. The codebase has measurable structural issues: circular imports in the API layer, duplicated handler logic, oversized files, and critical CI gaps (tests not invoked, no dependency scanning). The hygiene checks pass on tests/CI/license/lockfile/secret presence. It is suitable for individual or small-team home use where simplicity and low resource footprint matter more than developer ergonomics, but requires CI configuration fixes before it should be used in a production or collaborative context.