component-system/README.md

# 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:**
   ```bash
   mix deps.get
   ```

2. **Set up the database:**
   ```bash
   # 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:**
   ```bash
   mix phx.server
   ```

4. **Access the application:**
   - Open [http://localhost:4000](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
```bash
mix test
```

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

### Database Management
```bash
# 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:**
   ```bash
   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:**
   ```bash
   mix phx.gen.secret
   ```
   
   **Without Elixir/Phoenix (Linux/Unix):**
   ```bash
   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`):
   ```yaml
   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:**
   ```bash
   docker compose up -d
   ```

5. **Access:** [http://localhost:4000](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:**
   ```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. **Database setup:**
   ```bash
   _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