component-system/README.md

# Components Inventory - Elixir/Phoenix Implementation

A modern, idiomatic Elixir/Phoenix port of the original PHP-based component inventory management system.

## Features

### ✨ Improvements over the original PHP version:

1. **Modern Architecture**
   - Phoenix LiveView for real-time, reactive UI without JavaScript
   - Ecto for type-safe database operations
   - Proper separation of concerns with Phoenix contexts
   - Built-in validation and error handling

2. **Enhanced User Experience**
   - Real-time search with no page refreshes
   - Responsive design with Tailwind CSS
   - Loading states and better feedback
   - Improved mobile experience

3. **Better Data Management**
   - Full-text search with PostgreSQL
   - Hierarchical categories with parent-child relationships
   - Proper foreign key constraints
   - Database migrations for schema management

4. **Security & Reliability**
   - CSRF protection built-in
   - SQL injection prevention through Ecto
   - Session-based authentication
   - Input validation and sanitization

### 🔧 Core Functionality

- **Component Management**: Add, edit, delete, and track electronic components
- **Inventory Tracking**: Monitor component quantities with increment/decrement buttons
- **Search & Filter**: Fast search across component names, descriptions, and keywords
- **Category Organization**: Hierarchical category system for better organization
- **Category Management**: Add, edit, delete categories through the web interface with hierarchical support
- **Datasheet Links**: Direct links to component datasheets
- **Position Tracking**: Track component storage locations
- **Real-time Updates**: All changes are immediately reflected in the interface

## Setup

1. **Install dependencies:**
   ```bash
   mix deps.get
   ```

2. **Set up the database:**
   ```bash
   mix ecto.create
   mix ecto.migrate
   mix run priv/repo/seeds.exs
   ```

3. **Start the server:**
   ```bash
   mix phx.server
   ```

4. **Visit the application:**
   Open [http://localhost:4000](http://localhost:4000)

## Authentication

The application uses a simple password-based authentication system:
- Default password: `changeme`
- Set custom password via environment variable: `AUTH_PASSWORD=your_password`

## Database Schema

### Categories
- `id`: Primary key
- `name`: Category name (required)
- `description`: Optional description
- `parent_id`: Foreign key for hierarchical categories
- Supports unlimited nesting levels

### Components
- `id`: Primary key
- `name`: Component name (required)
- `description`: Detailed description
- `keywords`: Search keywords
- `position`: Storage location/position
- `count`: Current quantity (default: 0)
- `datasheet_url`: Optional link to datasheet
- `image_filename`: Optional image file name
- `category_id`: Required foreign key to categories

## Architecture

### Contexts
- **`ComponentsElixir.Inventory`**: Business logic for components and categories
- **`ComponentsElixir.Auth`**: Simple authentication system

### Live Views
- **`ComponentsElixirWeb.LoginLive`**: Authentication interface
- **`ComponentsElixirWeb.ComponentsLive`**: Main component management interface
- **`ComponentsElixirWeb.CategoriesLive`**: Category management interface

### Key Features
- **Real-time updates**: Changes are immediately reflected without page refresh
- **Infinite scroll**: Load more components as needed
- **Search optimization**: Uses PostgreSQL full-text search for long queries, ILIKE for short ones
- **Responsive design**: Works on desktop and mobile devices

## API Comparison

| Original PHP | New Elixir/Phoenix | Improvement |
|-------------|-------------------|-------------|
| `getItems.php` | `Inventory.list_components/1` | Type-safe, composable queries |
| `getCategories.php` | `Inventory.list_categories/0` | Proper associations, hierarchical support |
| `addItem.php` | `Inventory.create_component/1` | Built-in validation, changesets |
| Manual editing | `Inventory.update_component/2` | **NEW**: Full edit functionality with validation |
| `changeAmount.php` | `Inventory.update_component_count/2` | Atomic operations, constraints |
| Manual category management | `CategoriesLive` + `Inventory.create_category/1` | **NEW**: Full category CRUD with web interface |
| `imageUpload.php` | Phoenix LiveView file uploads with `.live_file_input` | **IMPLEMENTED**: Full image upload with preview, validation, and automatic cleanup |
| Session management | Phoenix sessions + LiveView | Built-in CSRF protection |

## 🚀 Future Enhancements

### Priority 1: Complete QR Code System (see [qr_storage_system](qr_storage_system.md))
- **QR Code Image Generation** - Add Elixir library (e.g., `qr_code` hex package) to generate actual QR code images
- **QR Code Display in Interface** - Show generated QR code images in the storage locations interface
- **Camera Integration** - JavaScript-based QR scanning with camera access for mobile/desktop
- **Multi-QR Code Detection** - Spatial analysis and disambiguation for multiple codes in same image

### Component Management
- **Barcode Support** - Generate and scan traditional barcodes in addition to QR codes
- **Bulk Operations** - Import/export components from CSV, batch updates
- **Search and Filtering** - Advanced search by specifications, tags, location
- **Component Templates** - Reusable templates for common component types
- **Version History** - Track changes to component specifications over time

### Storage Organization  
- **Physical Layout Mapping** - Visual representation of shelves, drawers, and boxes
- **Bulk QR Code Printing** - Generate printable sheets of QR codes for labeling

## ✅ Recently Implemented Features

### Storage Location System Foundation 🚧 **PARTIALLY IMPLEMENTED**
- **Database Schema** ✅ Complete - Hierarchical storage locations with parent-child relationships
- **Storage Location CRUD** ✅ Complete - Full create, read, update, delete operations via web interface
- **QR Code Data Generation** ✅ Complete - Text-based QR codes with format `SL:{level}:{code}:{parent}`
- **Hierarchical Organization** ✅ Complete - Unlimited nesting (shelf → drawer → box)
- **Web Interface** ✅ Complete - Storage locations management page with navigation
- **Component-Storage Integration** ❌ Missing - Linking components to storage locations not yet implemented correctly

### QR Code System - Still Needed 🚧 **NOT IMPLEMENTED**
- **Visual QR Code Generation** ❌ Missing - No actual QR code images are generated
- **QR Code Display** ❌ Missing - QR codes not shown in interface (as seen in screenshot)
- **QR Code Scanning** ❌ Missing - No camera integration or scanning functionality
- **QR Code Processing** ❌ Missing - Backend logic for processing scanned codes
- **Multi-QR Disambiguation** ❌ Missing - No handling of multiple QR codes in same image

### Image Upload System ✅ **COMPLETED**
- **Phoenix LiveView file uploads** with `.live_file_input` component
- **Image preview** during upload with progress indication
- **File validation** (JPG, PNG, GIF up to 5MB)
- **Automatic cleanup** of old images when updated or deleted
- **Responsive image display** in component listings with fallback placeholders
- **Upload error handling** with user-friendly messages

### Visual Datasheet Indicators ✅ **COMPLETED**
- **Datasheet emoji** (📄) displayed next to component names when datasheet URL is present
- **Clickable datasheet links** with clear visual indication
- **Improved component listing** with image thumbnails and datasheet indicators

### Technical Implementation Details

#### Image Upload Architecture
- **LiveView uploads** configured with `allow_upload/3` in mount
- **File processing** with `consume_uploaded_entries/3` for secure file handling
- **Unique filename generation** to prevent conflicts
- **Static file serving** through Phoenix.Plug.Static with `/uploads` path
- **Database integration** with `image_filename` field in components schema

#### Upload Features
- **File type validation**: Only JPG, PNG, GIF files accepted
- **Size limits**: Maximum 5MB per file
- **Single file uploads**: One image per component
- **Progress indication**: Real-time upload progress display
- **Cancel functionality**: Users can cancel uploads in progress
- **Preview system**: Live image preview before form submission

#### File Management
- **Automatic cleanup**: Old images deleted when new ones uploaded
- **Orphan prevention**: Images deleted when components are removed
- **Error handling**: Graceful fallback for missing or corrupted files
- **Static serving**: Images served directly through Phoenix static file handler

## Development

### Running Tests
```bash
mix test
```

### Code Quality
```bash
mix format
mix credo
```

### Database Management
```bash
# Reset database
mix ecto.reset

# Add new migration
mix ecto.gen.migration add_feature

# Check migration status
mix ecto.migrations
```

## Deployment

For production deployment:

1. **Set environment variables:**
   ```bash
   export AUTH_PASSWORD=your_secure_password
   export SECRET_KEY_BASE=your_secret_key
   export DATABASE_URL=postgresql://user:pass@host/db
   ```

2. **Build release:**
   ```bash
   MIX_ENV=prod mix release
   ```

3. **Run migrations:**
   ```bash
   _build/prod/rel/components_elixir/bin/components_elixir eval "ComponentsElixir.Release.migrate"
   ```

## Contributing

This is a modernized, idiomatic Elixir/Phoenix implementation that maintains feature parity with the original PHP version while providing significant improvements in code quality, security, and user experience.

The application follows Phoenix and Elixir best practices:
- Contexts for business logic
- LiveView for interactive UI
- Ecto for database operations
- Comprehensive error handling
- Input validation and sanitization