Data Models
ItemTracker uses a hierarchical data structure with Properties (for rental owners), Rooms, Containers, and Items. This document describes each entity's schema and the Firestore database structure.
Data Hierarchy
The app uses a hierarchy that adapts to the user type:
Homeowners
User Account
└── Rooms (physical spaces)
└── Containers (storage units)
└── Items (individual belongings)
Rental Owners (Pro)
User Account
└── Properties (rental properties)
└── Rooms (spaces within property)
└── Containers (storage units)
└── Items (individual belongings)
Items can be placed directly in rooms or inside containers. Each entity has a unique ID, timestamps, and optional photo references.
All entity IDs are generated client-side using UUID v4 to enable offline-first operations. IDs are preserved during cloud sync.
Room
Rooms represent physical spaces in your home or property.
Schema
{
id: string, // Unique identifier (UUID)
name: string, // Display name (e.g., "Garage")
photo: string | null, // Photo URI or Firebase Storage path
createdAt: number, // Unix timestamp (milliseconds)
updatedAt: number, // Last modification timestamp
userId: string // Owner's Firebase UID
}
Field Details
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Unique identifier, generated client-side |
name |
string | Yes | User-defined room name |
photo |
string | null | No | Local URI or Firebase Storage path |
createdAt |
number | Yes | Creation timestamp |
updatedAt |
number | Yes | Last update timestamp |
userId |
string | Yes | Firebase UID of the owner |
Example
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Garage",
"photo": "rooms/550e8400-e29b-41d4-a716-446655440000.jpg",
"createdAt": 1704067200000,
"updatedAt": 1704153600000,
"userId": "firebase-uid-123"
}
Container
Containers are storage units within rooms (shelves, boxes, drawers, etc.).
Schema
{
id: string, // Unique identifier (UUID)
name: string, // Display name (e.g., "Tool Drawer")
roomId: string, // Parent room's ID
photo: string | null, // Photo URI or Firebase Storage path
description: string | null, // Optional description
createdAt: number, // Unix timestamp (milliseconds)
updatedAt: number, // Last modification timestamp
userId: string // Owner's Firebase UID
}
Field Details
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Unique identifier |
name |
string | Yes | User-defined container name |
roomId |
string | Yes | ID of the parent room |
photo |
string | null | No | Container photo |
description |
string | null | No | Additional details |
createdAt |
number | Yes | Creation timestamp |
updatedAt |
number | Yes | Last update timestamp |
userId |
string | Yes | Owner's Firebase UID |
Example
{
"id": "661e9511-f39c-52e5-b827-557766551111",
"name": "Top Shelf",
"roomId": "550e8400-e29b-41d4-a716-446655440000",
"photo": null,
"description": "Holiday decorations and seasonal items",
"createdAt": 1704067200000,
"updatedAt": 1704153600000,
"userId": "firebase-uid-123"
}
Item
Items are individual belongings you want to track.
Schema
{
id: string, // Unique identifier (UUID)
name: string, // Display name
containerId: string | null, // Parent container (null if directly in room)
roomId: string, // Parent room's ID
photo: string | null, // Primary photo
photos: string[], // Additional photos (Premium)
category: string | null, // Item category
quantity: number, // Number of items (default: 1)
notes: string | null, // Additional notes
checkedOut: boolean, // Checkout status
checkedOutBy: string | null, // Who checked it out
checkedOutAt: number | null, // When it was checked out
createdAt: number, // Unix timestamp
updatedAt: number, // Last modification timestamp
userId: string // Owner's Firebase UID
}
Field Details
| Field | Type | Required | Description |
|---|---|---|---|
id |
string | Yes | Unique identifier |
name |
string | Yes | Item name (can be AI-generated) |
containerId |
string | null | No | Parent container ID (null = directly in room) |
roomId |
string | Yes | Parent room ID |
photo |
string | null | No | Primary item photo |
photos |
string[] | No | Additional photos (Premium feature) |
category |
string | null | No | Classification category |
quantity |
number | No | Count (default: 1) |
notes |
string | null | No | User notes, serial numbers, etc. |
checkedOut |
boolean | Yes | Whether item is currently checked out |
Categories
Common item categories include:
- Tools
- Electronics
- Clothing
- Books
- Games
- Kitchen
- Sports
- Holiday
- Documents
- Other
Checkout History
Tracks the history of item checkouts and returns.
Schema
{
id: string, // Unique identifier
itemId: string, // Reference to the item
action: string, // "checkout" or "return"
userId: string, // Who performed the action
userName: string, // Display name
notes: string | null, // Optional notes
timestamp: number // When the action occurred
}
Firestore Structure
Data is organized in Firestore using the following collection structure:
users/
{userId}/
rooms/
{roomId} // Room document
containers/
{containerId} // Container document
items/
{itemId} // Item document
checkoutHistory/
{historyId} // Checkout record
settings/
preferences // User settings document
Security Rules
Firestore security rules ensure users can only access their own data:
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /users/{userId}/{document=**} {
allow read, write: if request.auth != null
&& request.auth.uid == userId;
}
}
}
When household sharing is enabled, additional rules allow household members to access shared data. The household document maintains a list of member UIDs.
Local Storage
Data is also persisted locally using AsyncStorage for offline access:
Storage Keys
| Key | Content |
|---|---|
@ItemTracker:rooms |
JSON array of room objects |
@ItemTracker:containers |
JSON array of container objects |
@ItemTracker:items |
JSON array of item objects |
@ItemTracker:settings |
User preferences object |
@ItemTracker:lastSync |
Last sync timestamp |