box-manifest-android/README.md

Box Manifest

Box Manifest is a self-hosted physical inventory system built around one universal hierarchy. Locations, containers, and items are represented by the same kind of node, so any node can contain other nodes.

This repository currently contains:

• A Go HTTP server backed by SQLite
• A native Android client built with Kotlin and Jetpack Compose
• A Vite, React, and TypeScript web client
• An OpenAPI 3.1 contract

The project is pre-release and has no compatibility guarantee yet.

Current behavior

• Arbitrarily deep node hierarchy
• Optional non-negative integer quantities
• Single and bulk node creation
• Atomic single and multi-node moves
• Empty-only deletion
• Hierarchy search and breadcrumbs on Android and web
• JSON tree-import preview and atomic commit
• Stable six-character lookup codes
• QR-label preview/export on both clients, with scanning and visual Find on Android

See the universal-tree decision for the core model and the project plan for current boundaries and near-term direction.

Server development

The server requires Go 1.25 or newer.

cd server
go run ./cmd/box-manifest-server

SQLite data is stored at server/data/box-manifest.db by default and is ignored by Git.

Run the web development server in a separate terminal. It proxies API requests to the Go server and serves the client at http://localhost:5173:

cd web
npm install
npm run dev

For a production-style local build, run npm run build before starting the Go server. The server serves the generated web/dist directory at http://localhost:8080.

Available options:

go run ./cmd/box-manifest-server \
  -address :9000 \
  -database /path/to/box-manifest.db \
  -web ../web/dist

Run server tests with:

cd server
go test ./...

The API contract is api/openapi.yaml. The nested AI-import format is api/tree-import.schema.json.

Android development

The debug client currently connects to http://127.0.0.1:8080. Forward that port before running on a physical device connected through USB or wireless ADB:

adb reverse tcp:8080 tcp:8080

Build and verify from the command line with:

JAVA_HOME=/opt/android-studio/jbr \
ANDROID_HOME="$HOME/Android/Sdk" \
./gradlew :app:assembleDebug :app:testDebugUnitTest :app:lintDebug

The QR scanner uses Google Play services and may download its scanner module the first time it is opened. Label URLs also use the local development address until server configuration is introduced; do not print permanent labels yet.