Plings System Use Cases

This document provides a centralized overview of the primary use cases and user journeys within the Plings system. It is intended to be the starting point for understanding the system’s functional capabilities. Each use case links to more detailed technical and architectural documentation where available.

1. User Management

UC-101: User Registration & Authentication

  • As a new user, I want to create an account so that I can start using the Plings system.
  • As a returning user, I want to log in securely to access my objects and data.
  • Description: This involves creating a new user profile and authenticating via Supabase Auth. All subsequent API requests will be authenticated using a JWT.

UC-102: Configure Default Ownership

  • As a user, I want to configure the default ownership for newly created objects to streamline my workflow.
  • Description: A user can set a preference for who owns newly created objects. Options include: 1) The user’s personal account, 2) a specific organization the user belongs to, or 3) the owner of the container space where the object is created (system default).
  • Details: See batch_and_collection_management.md

2. Object & Data Management

UC-201: Create a New Object

  • As a user, I want to create a new object definition so that I can represent a physical or conceptual item in the system.
  • Description: A user creates a new object, giving it a name and description. This creates the core Object node in Neo4j and a corresponding security record in Supabase.
  • Details: See use_case_object_creation.md

UC-202: Upload an Image for an Object

  • As a user, I want to upload a primary image for an object to visually identify it.
  • Description: This is a two-step process involving a request to create an upload URL, followed by the actual file upload to Supabase Storage.
  • Details: See image_management.md

UC-203: Assign a Status to an Object

  • As a user, I want to assign or remove statuses (e.g., “for_sale”, “broken”) from an object to track its current state.
  • Description: The system allows multiple, simultaneous statuses to be associated with an object.
  • Details: See object_status_system.md

UC-204: Transfer Object Ownership

  • As a user, I want to transfer the ownership of an object to another user.
  • Description: This involves changing the ownership link in the Supabase security table, which governs access rights. The historical ownership can be tracked in the Neo4j graph for provenance.

3. Spatial Interaction (The Spatial Dashboard)

UC-301: Visualize Spatial Relationships

  • As a user, I want to see a clear, graphical layout of my objects and how they are spatially related to each other.
  • Description: The system renders a 2D or 3D view where the position of objects is determined by their relationships (left_of, above, etc.).
  • Details: See spatial_dashboard_requirements.md

UC-302: Create and Edit Spatial Relationships

  • As a user, I want to create a new spatial relationship between two objects by dragging one next to the other.
  • Description: Users can manipulate the layout directly via drag-and-drop or touch gestures. This action updates the underlying relationship data in the graph.
  • Details: See spatial_dashboard_requirements.md

UC-303: Move an Object Between Containers

  • As a user, I want to move an object from one container to another (e.g., from my “Toolbox” to my “Car”).
  • Description: This can be done by dragging an object onto a container object or a breadcrumb link in the spatial dashboard. This modifies the inside relationship.
  • Details: See spatial_dashboard_requirements.md

UC-304: Navigate Object Hierarchies

  • As a user, I want to navigate “into” a container object to see its contents.
  • Description: The UI provides interactive breadcrumbs and allows clicking on container objects to traverse the hierarchy. The view is updated using lazy loading for performance.
  • Details: See frontend_architecture.md and spatial_dashboard_requirements.md

UC-305: Inventory Audit & Misplacement Correction

  • As a user, I want to scan a container and its contents so the system can automatically update their current locations and highlight anything that is out of place.
  • Description: The user first scans a container to set its :IN relationship, then scans each contained object which updates their :IN edges to the container. The dashboard compares :IN versus :SHOULD_BE_IN, flags mismatches, and lets the user either accept the new expected location or add the items to a move collection.
  • Details: See spatial_relationships_system.md

UC-306: Checkout & Return Workflow

  • As an employee, I want to borrow a tool, have the system track that it is temporarily in my car, and automatically clear the mismatch when I return it.
  • Description: Scanning the tool and the car sets (:Tool)-[:IN]->(:Car) while its :SHOULD_BE_IN remains the workshop rack. The dashboard shows the object as misplaced (but mitigated by the lent_out status). When returned and rescanned into the rack, the mismatch is resolved.
  • Details: See spatial_relationships_system.md

4. Physical World Interaction & Information Retrieval

UC-401: Scan a Physical Identifier

  • As a user, I want to scan a QR code on a physical object to instantly view its digital twin in the app.
  • Description: Scanning a PlingsIdentifier logs a ScanEvent and retrieves the full details of the associated object. Supports both legacy identifiers and HD wallet-based identifiers with offline verification.
  • Details: See tag-scanning-integration.md and hd-wallet-identifier-creation.md

UC-402: Search for an Object

  • As a user, I want to search for an object by its name or other properties.
  • Description: The system must provide a search interface that queries the graph and returns a list of matching objects, respecting the user’s access rights.

UC-403: HD Wallet Identifier Creation

  • As a user/manufacturer, I want to generate cryptographically secure identifiers for objects with offline verification capabilities.
  • Description: Create identifiers using hierarchical deterministic wallets (BIP32) that enable offline authentication, anti-counterfeiting, and manufacturing batch operations. Supports both personal generic tags and manufacturer-issued authenticated identifiers.
  • Details: See hd-wallet-identifier-creation.md

5. Batch & Collection Management

UC-501: Batch Create New Objects

  • As a user, I want to rapidly create multiple objects in a specific location using my device’s camera, without entering details for each one immediately.
  • Description: This use case describes a camera-first workflow to create a temporary “batch” of objects. The objects are created with images, a container location, default ownership, and an “unprocessed” status. Data entry is deferred.
  • Details: See batch_and_collection_management.md

UC-502: Process Unfinished Objects

  • As a user, I want to easily find and complete the details for my unprocessed objects from a comfortable interface, like my desktop.
  • Description: The user can filter for objects with an “unprocessed” status. The UI provides a “Save and Next” workflow to efficiently add names, descriptions, and other details. This includes an option to use AI to suggest details based on the object’s image.
  • Details: See batch_and_collection_management.md

UC-503: Manage a Collection of Objects

  • As a user, I want to group arbitrary objects into a “collection” so I can organize them and perform actions on them all at once.
  • Description: A user can create a named collection, and then add or remove any object they have access to from that collection. This is for logical grouping, independent of spatial location.
  • Details: See batch_and_collection_management.md

UC-504: Perform Bulk Actions on a Collection

  • As a user, I want to select a collection and apply a single action to all objects within it, such as moving them or changing their owner.
  • Description: This covers bulk operations like “move all objects in this collection to a new container” or “transfer ownership of this entire collection to another user/organization.”
  • Details: See batch_and_collection_management.md

6. Access Control & Privacy

UC-601: Private Room Visibility

  • As a CEO, I want to hide every object inside my private room from regular employees so that sensitive equipment is not listed in their dashboards.
  • Description: Admin assigns deny OBJECT_READ ACL to Room-CEO-1 for the Org Everyone group and creates an allow ACL for the CEO_Private group. All objects inside the room inherit this rule.
  • Edge-Case Handling: Objects moved into the room by mistake become invisible to others; when scanned and moved out they automatically regain normal visibility.

UC-602: Family vs. Medicine Box

  • As a parent, I want my family to see all household items except the medicine box so children don’t interact with medicine records.
  • Description: The Family permission group has organisation-wide OBJECT_READ. A deny ACL on MedicineBox overrides the allow, hiding only that container.
  • Outcome: Family dashboards list every object except the contents of the medicine box; the owner still sees it via the owner-override rule.

7. Service Marketplace & Estate Management

UC-701: Storage using Plings

  • As a relative of a deceased person, I want to quickly document and store all belongings using Plings service providers so that I can clean out the residence immediately while preserving the option to properly distribute items among family members later.
  • Description: This use-case demonstrates how Plings can be used for estate management and storage services when an elderly person passes away. The system enables rapid object documentation, service provider marketplace integration, and deferred ownership decisions through storage logistics.
  • Details: See storage-estate-management.md