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.

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.

Current architecture

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/: dependency-free diagnostic UI
api/: OpenAPI contract and tree-import JSON Schema
docs/: product and architecture decisions

The API is intentionally unversioned during pre-release development.

Implemented vertical slices

Tree creation, reading, editing, moving, and empty-only deletion
Bulk sibling creation and multi-selection move/delete
Android 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 QR-label preview, sharing, and scanning

Near-term direction

Continue validating the Android interaction model and the server API against real inventory use. Prefer small end-to-end increments that exercise storage, API behavior, and the Android client together. Keep the web UI diagnostic until the core model and Android workflows have settled.

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.

3.6 KiB Raw Blame History