> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/lopiv2/invenicum/llms.txt
> Use this file to discover all available pages before exploring further.

# Inventory Management

> Organize items with containers, asset types, custom fields, and hierarchical collections

## Overview

Invenicum's inventory management system uses a flexible three-tier hierarchy:

**Containers** → **Asset Types** → **Items**

This structure lets you organize everything from IT equipment to collectibles with custom metadata tailored to each category.

<CardGroup cols={3}>
  <Card title="Containers" icon="box">
    Top-level organizational units (warehouses, rooms, projects)
  </Card>

  <Card title="Asset Types" icon="layer-group">
    Categories with custom field definitions (laptops, chairs, books)
  </Card>

  <Card title="Items" icon="barcode">
    Individual inventory entries with unique data
  </Card>
</CardGroup>

## Core Concepts

### Containers

Containers are the highest organizational level. Think of them as physical locations or logical groupings.

**Examples:**

* Office Building A
* Warehouse - Electronics
* Client Project: Acme Corp
* Personal Collection

<Note>
  Containers can be marked as **Collections** to enable special tracking features like "items owned" vs "items desired" for hobbyist use cases.
</Note>

**Creating a Container:**

<Steps>
  <Step title="Navigate to Containers">
    From the main dashboard, click "New Container" or use the sidebar menu.
  </Step>

  <Step title="Set Basic Info">
    Enter a name and optional description. Toggle "Is Collection" if tracking collectibles.
  </Step>

  <Step title="Configure Data Lists">
    Optionally create reusable dropdown lists for custom fields (see below).
  </Step>
</Steps>

Containers support **data lists**—predefined value sets for custom fields (lib/data/services/container\_service.dart:117):

```dart theme={null}
// Example: Creating a "Condition" data list
ContainerService.createDataList(
  containerId: 1,
  name: "Condition",
  description: "Item condition ratings",
  items: ["Mint", "Excellent", "Good", "Fair", "Poor"]
)
```

### Asset Types

Asset types define **what kind** of items you're tracking and **what data** to collect for each.

**Key Features:**

* **Custom Field Definitions**: Text, numbers, dates, dropdowns, images
* **Serialization Toggle**: Enable unique identifiers for trackable items
* **Visual Icons**: Upload images to distinguish types at a glance
* **Collection Fields**: For collectibles, designate fields for "quantity owned" vs "quantity wanted"

**Field Definition Example:**

```json theme={null}
[
  {
    "id": "manufacturer",
    "label": "Manufacturer",
    "type": "text",
    "required": true
  },
  {
    "id": "purchase_date",
    "label": "Purchase Date",
    "type": "date",
    "required": false
  },
  {
    "id": "condition",
    "label": "Condition",
    "type": "list",
    "listId": 5,
    "required": true
  }
]
```

<Tip>
  Use **list fields** tied to container data lists for consistent data entry across your team.
</Tip>

**Creating an Asset Type:**

<Steps>
  <Step title="Select Container">
    Navigate to the container where this asset type will live.
  </Step>

  <Step title="Add Asset Type">
    Click "New Asset Type" and enter a name (e.g., "Laptops", "Office Chairs").
  </Step>

  <Step title="Define Fields">
    Add custom fields that match the metadata you need to track.

    Common patterns:

    * Electronics: Model, Serial Number, Warranty Date
    * Furniture: Dimensions, Color, Material
    * Books: ISBN, Author, Publication Year
  </Step>

  <Step title="Upload Icon (Optional)">
    Add a representative image to visually identify this asset type.
  </Step>
</Steps>

### Items

Items are the actual inventory entries. Each item belongs to exactly one asset type within a container.

**Core Fields:**

* **Name**: Required, searchable
* **Description**: Optional rich text
* **Barcode**: Supports scanning and QR code generation
* **Quantity**: Track stock levels
* **Min Stock**: Set reorder thresholds
* **Location**: Optional physical location reference
* **Custom Field Values**: Data matching the parent asset type's schema
* **Images**: Multiple photos with alt text
* **Market Value**: Track pricing and history

**Creating an Item:**

<Steps>
  <Step title="Navigate to Asset Type">
    Go to Container → Asset Type → "Add Item"
  </Step>

  <Step title="Fill Core Fields">
    Enter name, description, quantity, and barcode if applicable.
  </Step>

  <Step title="Add Custom Data">
    Complete the custom fields defined by the asset type.

    <Tip>Use the AI Assistant to auto-fill from a product URL!</Tip>
  </Step>

  <Step title="Upload Images">
    Attach photos. The first image becomes the primary thumbnail.
  </Step>

  <Step title="Set Market Value (Optional)">
    Enter current market price. Invenicum can sync this with UPC databases for barcode-enabled items.
  </Step>

  <Step title="Save">
    Click "Create Item" to add it to your inventory.
  </Step>
</Steps>

## Advanced Features

### Batch Import

Import hundreds of items at once from CSV or Excel files (lib/data/services/inventory\_item\_service.dart:264):

1. Prepare a spreadsheet with columns matching your asset type's fields
2. Navigate to the asset type
3. Click "Import" and upload your file
4. Map columns to fields
5. Review and confirm

<Warning>
  Batch imports cannot include image uploads. Add images individually after import.
</Warning>

### Item Cloning

Duplicate similar items quickly (lib/data/services/inventory\_item\_service.dart:81):

1. View an existing item
2. Click "Clone"
3. Images and custom fields are copied
4. Adjust unique fields (name, barcode, quantity)
5. Save the new item

### Low Stock Alerts

Set `minStock` thresholds per item. The dashboard shows items below their minimum (lib/data/models/dashboard\_stats.dart:10).

### Global Search

Search across all containers and asset types (lib/data/services/container\_service.dart:41):

```
ContainerService.searchItemsGlobal("Dell XPS")
```

Returns matching items with container and asset type context.

## Organizing Collections

For hobbyists tracking collectibles (stamps, cards, coins), enable **Collection Mode** on your container:

1. Mark container as "Is Collection" during creation
2. In each asset type, designate:
   * **Possession Field**: Which field tracks quantity owned
   * **Desired Field**: Which field tracks quantity wanted
3. Use the collection dashboard to see completion percentages

**Example: Trading Card Collection**

* Container: "Pokémon Cards 2024"
* Asset Type: "Base Set"
* Fields:
  * `card_number` (text)
  * `owned` (number) ← Possession Field
  * `needed` (number) ← Desired Field
  * `condition` (list)

## Market Value Tracking

Invenicum can track the financial value of your inventory:

* **Manual Entry**: Set `marketValue` and `currency` per item
* **UPC Sync**: For items with barcodes, sync pricing from external databases (lib/data/services/inventory\_item\_service.dart:346)
* **Price History**: Automatic tracking of value changes over time
* **Total Portfolio Value**: Dashboard shows aggregate value across all items

<Note>
  Price history is recorded each time an item's market value changes, enabling trend analysis.
</Note>

## Best Practices

<CardGroup cols={2}>
  <Card title="Consistent Naming" icon="tag">
    Use clear, searchable names: "Dell Latitude 5520" not "John's Laptop"
  </Card>

  <Card title="Leverage Barcodes" icon="barcode">
    Add barcodes/UPCs to enable QR scanning and market value sync
  </Card>

  <Card title="Meaningful Custom Fields" icon="list-check">
    Only create fields you'll actually populate and use for filtering
  </Card>

  <Card title="Regular Audits" icon="calendar-check">
    Periodically verify quantities and update market values
  </Card>
</CardGroup>

## API Reference

See the API documentation for detailed information on:

* Container Service - Container/collection management API
* Asset Type Service - Asset type and custom field definitions API
* Inventory Item Service - CRUD operations for inventory items
* InventoryItem Model - Complete item data structure