106 lines
3.8 KiB
Markdown
106 lines
3.8 KiB
Markdown
# Box Manifest project plan
|
|
|
|
Status: working pre-release prototype
|
|
Last updated: 2026-08-26
|
|
|
|
## Product direction
|
|
|
|
Box Manifest is a self-hosted system for recording what exists and where it is
|
|
stored. The server owns the data and domain rules. Android is the primary
|
|
client during early development; the web client currently exists only as a
|
|
minimal diagnostic interface.
|
|
|
|
There are no users or compatibility obligations. API, schema, and client code
|
|
may change freely while the architecture is being established.
|
|
|
|
## Core model
|
|
|
|
The inventory is one rooted tree of universal nodes. The system does not
|
|
assign structural kinds such as location, container, or item. A node can
|
|
represent any physical or conceptual thing and can contain other nodes.
|
|
|
|
```text
|
|
Root
|
|
└── Apartment
|
|
└── Room
|
|
└── Shelf
|
|
└── Box
|
|
└── Pens (quantity: 10)
|
|
```
|
|
|
|
A node currently has:
|
|
|
|
- An internal opaque ID
|
|
- A stable, human-enterable lookup code
|
|
- One parent, except for Root
|
|
- A required name
|
|
- An optional non-negative integer quantity
|
|
- Zero or more children
|
|
|
|
Root and Unsorted are protected system nodes. Unsorted is the inbox for nodes
|
|
whose placement has not been decided.
|
|
|
|
## Settled hierarchy rules
|
|
|
|
- Moving a node with `WITH_SUBTREE` moves all descendants with it.
|
|
- `PROMOTE_CHILDREN` reparents direct children to the node's former parent.
|
|
- `CHILDREN_TO_UNSORTED` reparents direct children to Unsorted.
|
|
- Multi-node mutations are atomic.
|
|
- Moves that create cycles are rejected.
|
|
- Deletion is allowed only for empty, non-system nodes.
|
|
- Quantity is optional; missing and zero are distinct.
|
|
- Names need not be unique and are never identifiers.
|
|
|
|
These decisions are recorded in
|
|
[ADR 0001](decisions/0001-universal-node-tree.md).
|
|
|
|
## Current architecture
|
|
|
|
```text
|
|
Android ───┐
|
|
├── HTTP API ──> Go server ──> SQLite
|
|
Web ───────┘
|
|
```
|
|
|
|
- `server/`: Go standard-library HTTP handlers and SQLite persistence
|
|
- `app/`: Kotlin, Jetpack Compose, coroutines, and a small handwritten client
|
|
- `web/`: Vite, React, and TypeScript client
|
|
- `api/`: OpenAPI contract and tree-import JSON Schema
|
|
- `docs/`: product and architecture decisions
|
|
|
|
The API is intentionally unversioned during pre-release development.
|
|
|
|
Web styling follows the pinned [desktop design reference](design/DESKTOP_DESIGN_REFERENCE.md).
|
|
Visual changes are reviewed against its exact tokens, fixtures, and documented
|
|
Box Manifest deviations rather than a general product resemblance.
|
|
|
|
## Implemented vertical slices
|
|
|
|
- Tree creation, reading, editing, moving, and empty-only deletion
|
|
- Bulk sibling creation and multi-selection move/delete
|
|
- Android and web hierarchy navigation, breadcrumbs, and local search
|
|
- AI-oriented nested JSON import with preview and atomic commit
|
|
- Stable lookup codes and canonical `/n/{code}` routes
|
|
- Android and web QR-label preview/export, plus Android camera scanning and Find
|
|
|
|
## Near-term direction
|
|
|
|
Continue validating the shared Android/web interaction model and the server API
|
|
against real inventory use. Prefer small end-to-end increments that exercise
|
|
storage, API behavior, and both clients together. Camera-dependent workflows
|
|
remain Android-specific.
|
|
|
|
Before permanent QR labels are printed, make the server's externally reachable
|
|
canonical URL configurable. Before deployment work begins, establish explicit
|
|
configuration and migration conventions for the pre-release server.
|
|
|
|
## Quality expectations
|
|
|
|
- Database constraints and transactions protect tree integrity.
|
|
- Server behavior is covered with SQLite-backed tests.
|
|
- Android changes pass compilation, unit tests, and lint.
|
|
- Durable server data remains outside version control.
|
|
- QR codes contain stable lookup URLs, never names or hierarchy paths.
|
|
- Documentation describes implemented behavior separately from ideas under
|
|
discussion.
|