Electronic Components Inventory System

A modern, comprehensive electronic component inventory management system built with Elixir/Phoenix LiveView. Features real-time updates, hierarchical organization, and advanced search capabilities.

Features

🔧 Core Functionality

• Component Management: Add, edit, delete, and track electronic components with real-time updates
• Inventory Tracking: Monitor component quantities with increment/decrement buttons
• Advanced Search & Filtering:
  • Fast full-text search across component names, descriptions, and keywords
  • Filter by categories and storage locations (including subcategories/sublocations)
  • Clickable category and location filters for quick navigation
• Hierarchical Organization:
  • Unlimited nesting for both categories and storage locations
  • Collapsible tree views for easy navigation
  • Visual breadcrumb paths (e.g., "Electronics > Resistors > Through-hole")
• Datasheet Management:
  • Upload PDF datasheets directly or provide URLs for automatic download
  • Automatic datasheet retrieval from URLs with validation
  • Visual indicators for components with datasheets
  • Direct PDF viewing and download
• Storage Location System:
  • Hierarchical locations (shelf → drawer → box) with AprilTag integration
  • Automatic AprilTag generation for physical labeling
  • Downloadable SVG AprilTags for printing
• Image Support: Upload component images with preview and validation
• Real-time Interface: All changes reflected immediately without page refresh

🎨 User Experience

• Modern Responsive Design: Works seamlessly on desktop and mobile
• Dark/Light Mode: Automatic theme support with DaisyUI
• Interactive Components:
  • Collapsible hierarchical views
  • Focus mode for detailed component viewing
  • Drag-and-drop file uploads with progress indicators
• Smart Navigation: Clickable categories and locations for instant filtering
• Visual Feedback: Loading states, progress bars, and clear error messages

Quick Start

Prerequisites

• Elixir 1.15+
• PostgreSQL 15+
• Docker (optional, for containerized deployment)

Development Setup

1. Install dependencies:

   mix deps.get
   

2. Set up the database:

   # Using Docker (recommended)
   docker run --name components-postgres -p 5432:5432 \
     -e POSTGRES_PASSWORD=fCnPB8VQdPkhJAD29hq6sZEY -d postgres
   
   # Initialize database
   mix ecto.create
   mix ecto.migrate
   mix run priv/repo/seeds.exs
   

3. Start the development server:

   mix phx.server
   

4. Access the application:

   • Open http://localhost:4000
   • Default password: changeme

Authentication

Simple password-based authentication:

• Default: changeme
• Custom: Set AUTH_PASSWORD=your_password environment variable

Database Schema

Categories (Hierarchical)

• id: Primary key
• name: Category name (required)
• description: Optional description
• parent_id: Foreign key for hierarchical structure
• Features: Unlimited nesting, full-path display, clickable filtering

Storage Locations (Hierarchical)

• id: Primary key
• name: Location name (required)
• description: Optional description
• parent_id: Foreign key for hierarchical structure
• apriltag_id: Optional AprilTag identifier for physical labeling
• Features: AprilTag generation, SVG download, hierarchical filtering

Components

• id: Primary key
• name: Component name (required)
• description: Detailed description
• keywords: Search keywords
• count: Current quantity (default: 0)
• category_id: Required foreign key to categories
• storage_location_id: Optional foreign key to storage locations
• datasheet_url: Optional URL to external datasheet
• datasheet_filename: Optional uploaded PDF datasheet
• image_filename: Optional uploaded component image

Technical Architecture

Phoenix LiveView Application

• Real-time updates: No page refreshes needed
• Phoenix Contexts: Clean separation of business logic
• Ecto: Type-safe database operations with migrations
• Authentication: Session-based with CSRF protection

Key Modules

• ComponentsElixir.Inventory: Core business logic
• ComponentsElixir.DatasheetDownloader: Automatic PDF retrieval
• ComponentsElixir.AprilTag: SVG AprilTag generation
• ComponentsElixir.Inventory.Hierarchical: Reusable hierarchy management
• ComponentsElixirWeb.*Live: LiveView interfaces for real-time UI

Recent Features & Improvements

✅ Datasheet Management System

• Automatic Download: Provide a URL and the system downloads the PDF automatically
• Direct Upload: Upload PDF datasheets up to 10MB
• Smart Validation: Ensures uploaded files are valid PDFs
• Visual Indicators: Components with datasheets show clear visual cues
• Integrated Viewing: Click component names to view datasheets directly

✅ Advanced Filtering & Navigation

• Hierarchical Filtering: Filter by categories/locations including all subcategories/sublocations
• Click-to-Filter: Click any category or location name to instantly filter components
• Collapsible Trees: Expand/collapse category and storage location hierarchies
• Smart Search: Combines full-text search with hierarchical filtering

✅ Enhanced User Interface

• Focus Mode: Detailed component view with full information display
• Responsive Design: Optimized for mobile and desktop usage
• Consistent Sorting: Robust sorting even with rapid data changes
• Visual Feedback: Loading states, progress indicators, and clear error messages

✅ Production-Ready Deployment

• Docker Support: Complete containerized deployment with database
• File Upload Optimization: Improved handling in production environments
• Performance Tuning: Optimized queries and caching for better responsiveness

Future Enhancements

Component Management

• Barcode Support: Generate and scan traditional barcodes alongside AprilTags
• Camera Integration: Mobile/desktop AprilTag scanning with camera access
• Multi-Tag Detection: Spatial analysis for multiple tags in the same view
• Bulk Operations: CSV import/export and batch component updates
• Component Templates: Reusable templates for common component types
• Specifications Tracking: Detailed technical specifications with custom fields
• Version History: Track changes to component data over time

Advanced Features

• API Integration: Connect with distributor APIs for price and availability
• Low Stock Alerts: Automatic notifications for components below threshold
• Bill of Materials (BOM): Project-based component tracking and allocation
• Purchase History: Track component purchases and supplier information
• Location Mapping: Visual representation of physical storage layout

AprilTag Enhancement

• Scanner App: Dedicated mobile app for inventory management
• Batch Printing: Generate printable sheets of multiple AprilTags
• Smart Scanning: Context-aware actions based on scanned tags

Development

Running Tests

mix test

Code Quality

mix format
mix credo

Database Management

# Reset database
mix ecto.reset

# Create new migration
mix ecto.gen.migration add_feature

# Check migration status
mix ecto.migrations

Development Environment

The project includes:

• Hot code reloading for rapid development
• TailwindCSS with live recompilation
• DaisyUI for consistent component styling
• Database seeding with sample data

Deployment

🐳 Docker Deployment (Recommended)

Docker provides the easiest deployment method with a pre-built container image including all dependencies.

Quick Start

1. Download the docker-compose file:

   curl -O https://git.maxboeer.com/schuwi/component-system/raw/branch/main/docker-compose.yml.example
   mv docker-compose.yml.example docker-compose.yml
   

2. Generate a secure secret key:

   With Elixir/Phoenix installed:

   mix phx.gen.secret
   

   Without Elixir/Phoenix (Linux/Unix):

   dd if=/dev/random bs=1 count=64 status=none | base64 -w0 | cut -c1-64
   

   Note

   : The SECRET_KEY_BASE must be a cryptographically random string that's at least 64 characters long. Phoenix uses it to sign session cookies, CSRF tokens, and other security-sensitive data.

3. Configure environment (edit docker-compose.yml):

   environment:
     SECRET_KEY_BASE: "your-generated-64-character-secret-key"
     AUTH_PASSWORD: "your-secure-password" # Login password for the app
     PHX_HOST: "localhost"  # Change to your domain
   

4. Deploy:

   docker compose up -d
   

5. Access: http://localhost:4000

The container image is automatically built and published from the main branch at https://git.maxboeer.com/schuwi/component-system.

Production Configuration

For production environments:

• Use specific versions: Pin to specific tags like git.maxboeer.com/schuwi/components-elixir:v1.0.0 instead of :latest
• Available tags:
  • :latest - Latest stable release from main branch
  • :main - Latest build from main branch
  • :v* - Specific version tags
  • :snapshot-<hash> - Specific commit builds
• Generate secure keys: Generate a 64+ character random string for SECRET_KEY_BASE (see Quick Start section for methods)
• Set strong passwords: Use AUTH_PASSWORD environment variable
• Configure domain: Set PHX_HOST to your actual domain
• Database security: Use strong PostgreSQL credentials
• SSL/HTTPS: Configure reverse proxy (nginx, Caddy) for SSL termination

🚀 Traditional Deployment

For deployment without Docker:

1. Environment setup:

   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. Database setup:

   _build/prod/rel/components_elixir/bin/components_elixir eval "ComponentsElixir.Release.migrate"
   

Contributing

This project follows Phoenix and Elixir best practices:

• Phoenix Contexts for business logic separation
• LiveView for real-time, interactive user interfaces
• Ecto for type-safe database operations
• Comprehensive testing with ExUnit
• Input validation and sanitization throughout
• CSRF protection and security best practices

The codebase emphasizes:

• Maintainability: Clear module organization and documentation
• Performance: Optimized queries and efficient data structures
• Reliability: Comprehensive error handling and graceful degradation
• Extensibility: Modular design for easy feature additions