97 lines
2.6 KiB
Markdown
97 lines
2.6 KiB
Markdown
# 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.
|