# 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](docs/decisions/0001-universal-node-tree.md)
for the core model and [the project plan](docs/PROJECT_PLAN.md) for current
boundaries and near-term direction.

## Server development

The server requires Go 1.25 or newer.

```bash
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`:

```bash
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:

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

Run server tests with:

```bash
cd server
go test ./...
```

The API contract is [api/openapi.yaml](api/openapi.yaml). The nested AI-import
format is [api/tree-import.schema.json](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:

```bash
adb reverse tcp:8080 tcp:8080
```

Build and verify from the command line with:

```bash
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.