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
• Storage Location System: Hierarchical storage locations (shelf → drawer → box) with automatic AprilTag generation
• AprilTag Integration: Automatic AprilTag generation and display for all storage locations with download capability
• Datasheet Links: Direct links to component datasheets
• Real-time Updates: All changes are immediately reflected in the interface

Setup

1. Install dependencies:

   mix deps.get
   

2. Set up the database:

   mix ecto.create
   mix ecto.migrate
   mix run priv/repo/seeds.exs
   

3. Start the server:

   mix phx.server
   

4. Visit the application: Open 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
• ComponentsElixirWeb.StorageLocationsLive: Hierarchical storage location management with AprilTags

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
Manual location tracking	StorageLocationsLive + Inventory context	NEW: Hierarchical storage locations with automatic AprilTags
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

Component Management

• Barcode Support - Generate and scan traditional barcodes in addition to AprilTags
• Camera Integration - JavaScript-based AprilTag scanning with camera access for mobile/desktop
• Multi-AprilTag Detection - Spatial analysis and disambiguation for multiple tags in same image
• 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 AprilTag Printing - Generate printable sheets of AprilTags for labeling

✅ Recently Implemented Features

Storage Location System Foundation ✅ COMPLETED

• Database Schema ✅ Complete - Hierarchical storage locations with parent-child relationships
• Storage Location CRUD ✅ Complete - Full create, read, update, delete operations via web interface
• Hierarchical Organization ✅ Complete - Unlimited nesting (shelf → drawer → box)
• Web Interface ✅ Complete - Storage locations management page with navigation
• Component-Storage Integration ✅ Complete - Components can now be assigned to storage locations via dropdown interface

AprilTag System 🚧 PARTIALLY IMPLEMENTED

• Visual AprilTag Generation ❌ Partially Implemented - Placeholder SVGs generated
• Flexible Assignment Options ✅ Complete - Auto-assign, manual selection, or no AprilTag assignment for storage locations
• AprilTag Download ✅ Complete - Individual AprilTag SVG files can be downloaded for printing
• AprilTag Scanning ❌ Missing - No camera integration or scanning functionality (future enhancement)
• AprilTag Processing ❌ Missing - Backend logic for processing scanned tags (future enhancement)

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

mix test

Code Quality

mix format
mix credo

Database Management

# 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:

   export AUTH_PASSWORD=your_secure_password
   export SECRET_KEY_BASE=your_secret_key
   export DATABASE_URL=postgresql://user:pass@host/db
   

2. Build release:

   MIX_ENV=prod mix release
   

3. Run migrations:

   _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