# 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.