diff --git a/README.md b/README.md index 10792c8..88a56ae 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,52 @@ -# Components Inventory - Elixir/Phoenix Implementation +# Electronic Components Inventory System -A modern, idiomatic Elixir/Phoenix port of the original PHP-based component inventory management 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 -### ✨ 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 +- **Component Management**: Add, edit, delete, and track electronic components with real-time updates - **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 +- **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 -## Setup +### 🎨 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 @@ -51,144 +55,122 @@ A modern, idiomatic Elixir/Phoenix port of the original PHP-based component inve 2. **Set up the database:** ```bash - docker run --name components-postgres -p 5432:5432 -e POSTGRES_PASSWORD=fCnPB8VQdPkhJAD29hq6sZEY -d postgres # password: config/dev.exs + # 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 server:** +3. **Start the development server:** ```bash mix phx.server ``` -4. **Visit the application:** - Open [http://localhost:4000](http://localhost:4000) +4. **Access the application:** + - Open [http://localhost:4000](http://localhost:4000) + - Default password: `changeme` -## Authentication +### Authentication -The application uses a simple password-based authentication system: -- Default password: `changeme` -- Set custom password via environment variable: `AUTH_PASSWORD=your_password` +Simple password-based authentication: +- Default: `changeme` +- Custom: Set `AUTH_PASSWORD=your_password` environment variable ## Database Schema -### Categories +### Categories (Hierarchical) - `id`: Primary key - `name`: Category name (required) - `description`: Optional description -- `parent_id`: Foreign key for hierarchical categories -- Supports unlimited nesting levels +- `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 -- `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 +- `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 -## Architecture +## Technical Architecture -### Contexts -- **`ComponentsElixir.Inventory`**: Business logic for components and categories -- **`ComponentsElixir.Auth`**: Simple authentication system +### 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 -### 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 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 -### 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 +### ✅ 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 -## API Comparison +### ✅ 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 -| 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 | +### ✅ 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 -## 🚀 Future Enhancements +### ✅ 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 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 +- **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 -### Storage Organization -- **Physical Layout Mapping** - Visual representation of shelves, drawers, and boxes -- **Bulk AprilTag Printing** - Generate printable sheets of AprilTags for labeling +### 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 -## ✅ 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 +### 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 @@ -199,7 +181,7 @@ mix test ### Code Quality ```bash -mix format +#mix format - nope, not yet mix credo ``` @@ -208,151 +190,65 @@ mix credo # Reset database mix ecto.reset -# Add new migration +# 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) -#### Prerequisites -- Docker and Docker Compose installed -- Git for cloning the repository +Docker provides the easiest deployment method with all dependencies included. #### Quick Start -1. **Clone the repository:** +1. **Clone and setup:** ```bash git clone cd components_elixir + cp docker-compose.yml.example docker-compose.yml ``` -2. **Copy docker-compose.yml.example to docker-compose.yml** - Follow steps in [Customizing Docker Deployment](#customizing-docker-deployment). +2. **Configure environment** (edit `docker-compose.yml`): + ```yaml + environment: + SECRET_KEY_BASE: "your-64-character-secret-key" # Generate with: mix phx.gen.secret + AUTH_PASSWORD: "your-secure-password" + PHX_HOST: "localhost" # Change to your domain + ``` -3. **Build and run with Docker Compose:** +3. **Deploy:** ```bash docker compose up --build ``` - **⚠️ Build Time Notice**: The initial build can take 5-15 minutes because: - - Tailwind CSS downloads ~500MB from GitHub (can be very slow) - - ESBuild downloads additional build tools - - Elixir compiles all dependencies - - Network conditions may significantly affect download speeds +4. **Access:** [http://localhost:4000](http://localhost:4000) -4. **Access the application:** - - Open [http://localhost:4000](http://localhost:4000) - - Default password: `changeme` - -#### Docker Configuration Files - -The project includes these Docker files: - -- **`Dockerfile`** - Multi-stage build for production -- **`docker-compose.yml`** - Local development/testing setup -- **`.dockerignore`** - Excludes unnecessary files from build context - -#### Customizing Docker Deployment - -1. **Environment Variables**: Edit `docker-compose.yml` to customize: - ```yaml - environment: - DATABASE_URL: "ecto://postgres:postgres@db:5432/components_elixir_prod" - SECRET_KEY_BASE: "your-secret-key-here" # Generate with: mix phx.gen.secret - PHX_HOST: "localhost" # Change to your domain - PHX_SERVER: "true" - PORT: "4000" - ``` - -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. **Database Configuration**: The default setup includes: - - PostgreSQL 15 container - - Automatic database creation - - Health checks to ensure proper startup order - - Persistent data storage with Docker volumes - -#### Production Docker Deployment +#### Production Configuration For production environments: -1. **Create a production docker-compose.yml:** - ```yaml - services: - db: - image: postgres:15 - environment: - POSTGRES_USER: components_user - POSTGRES_PASSWORD: secure_db_password - POSTGRES_DB: components_elixir_prod - volumes: - - postgres_data:/var/lib/postgresql/data - restart: unless-stopped - - app: - build: . - ports: - - "80:4000" - environment: - DATABASE_URL: "ecto://components_user:secure_db_password@db:5432/components_elixir_prod" - SECRET_KEY_BASE: "your-64-char-secret-key" - PHX_HOST: "yourdomain.com" - PHX_SERVER: "true" - PORT: "4000" - depends_on: - db: - condition: service_healthy - restart: unless-stopped - command: ["/bin/sh", "-c", "/app/bin/migrate && /app/bin/server"] - - volumes: - postgres_data: - ``` - -2. **Deploy to production:** - ```bash - docker compose -f docker-compose.prod.yml up -d - ``` - -#### Docker Troubleshooting - -**Build Issues:** -- **Slow Tailwind download**: This is normal - GitHub releases can be slow -- **Network timeouts**: Retry the build with `docker compose up --build` -- **AprilTag compilation errors**: Ensure `apriltags.ps` file exists in project root - -**Runtime Issues:** -- **Database connection errors**: Wait for PostgreSQL health check to pass -- **Permission errors**: Check file ownership and Docker user permissions -- **Port conflicts**: Change the port mapping in docker-compose.yml - -**Performance:** -- **Slow startup**: First-time container startup includes database initialization -- **Memory usage**: Elixir/Phoenix applications typically use 50-200MB RAM -- **Storage**: PostgreSQL data persists in Docker volumes +- **Generate secure keys**: Use `mix phx.gen.secret` for SECRET_KEY_BASE +- **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 production deployment without Docker: +For deployment without Docker: -1. **Set environment variables:** +1. **Environment setup:** ```bash export AUTH_PASSWORD=your_secure_password export SECRET_KEY_BASE=your_secret_key @@ -364,18 +260,24 @@ For production deployment without Docker: MIX_ENV=prod mix release ``` -3. **Run migrations:** +3. **Database setup:** ```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. +This project follows Phoenix and Elixir best practices: -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 \ No newline at end of file +- **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 \ No newline at end of file