# TFM aInventory

## What This Is

A unified inventory management system combining web administration, field scanning (QR/barcode), AI-powered label extraction, and offline sync. Organizations use it to maintain accurate stock levels across distributed locations with minimal friction.

## Core Value

**One-click stock accuracy with minimal manual data entry** — Users scan items, AI extracts details, offline sync prevents data loss.

## Requirements

### Validated

- ✓ Item CRUD with barcode/part number tracking — v1.0
- ✓ QR/barcode scanning with html5-qrcode (offline) — v1.1
- ✓ AI label extraction (Gemini 2.0 Flash) — v1.3
- ✓ Multi-AI provider support (Claude 3.5 Sonnet as fallback) — v1.9.23
- ✓ Offline sync with IndexedDB + UUID idempotency — v1.5
- ✓ LDAP + PBKDF2 credential caching for offline auth — v1.4
- ✓ Admin dashboard with user/category/config management — v1.10
- ✓ Audit logging with immutable trails (no deletion) — v1.4
- ✓ Image adjustment modal (rotation-only) for onboarding — v1.14.6
- ✓ PWA with service workers + manifest (iOS/Android) — v1.3

### Active

- [ ] Define v2 feature priorities (0-3 months)
- [ ] Clarify performance/scale requirements
- [ ] User feedback integration from field deployments
- [ ] Mobile UX refinements (touch gestures, small-screen affordances)

### Out of Scope

- **Cropping functionality** — Non-essential for MVP; rotation covers 90% of use case
- **Advanced analytics** — Deferred to v3; audit logs provide raw data
- **Multi-warehouse federation** — Single-instance per organization; federation is v3+
- **Custom field schemas** — Predefined Item/Category structure proven sufficient
- **Real-time collaborative editing** — Not needed; async batch operations match field workflow

## Context

**Project Status:** v1.14.6 stable, phase 3 complete
- Core platform shipping with ImageAdjustmentModal for better UX
- Recent focus: simplifying image handling (removed unnecessary rotation modal double-apply, fixed canvas zoom/rotation)
- Field deployments active; user feedback indicates system is working

**Tech Environment:**
- Backend: FastAPI + SQLite + SQLAlchemy (Python 3.12+)
- Frontend: Next.js 15 + Tailwind + Lucide Icons
- PWA: Offline-first with service workers + IndexedDB
- AI: Gemini 2.0 Flash (primary) + Claude 3.5 Sonnet (fallback)

**Known Issues:**
- Feature prioritization unclear (too many options, no v2 direction)
- Mobile UX polish needed (gesture handling, responsive edge cases)
- Documentation gaps around config management and deployment

## Constraints

- **Tech Stack**: FastAPI, SQLite, Next.js — established; changing requires major rewrite
- **AI Flexibility**: Support multiple providers (Gemini/Claude); single-provider lock-in is unacceptable
- **Offline-First**: System MUST work without network; sync is async not real-time
- **Auth Model**: LDAP + local credential caching; enterprise directory integration required
- **Database**: SQLite only; multi-instance deployment not supported in v1-2
- **UI Fidelity**: Premium aesthetics (Tailwind, Lucide, no UPPERCASE, no BOLD fonts)

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| SQLite + file-based DB | Single-instance simplicity, zero ops overhead | ✓ Good — eliminates infrastructure burden |
| Multi-AI providers (Gemini + Claude) | Resilience + cost optimization (fallback if primary fails) | ✓ Good — proven in production |
| Offline-first sync with UUIDs | Field work often has spotty connectivity | ✓ Good — prevents data loss |
| PBKDF2 credential caching | Support offline login without plaintext storage | ✓ Good — enterprise security + offline UX |
| Rotation-only image adjustment (no crop) | Crop was non-functional UI; rotation covers real use case | ✓ Good — simplified modal, fixed zoom issues |
| Service Worker PWA | Mobile field workers need installable app | ✓ Good — works on iOS/Android |

---

*Last updated: 2026-04-22 after reset (lost priority focus)*