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
- **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

### 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 |
| `imageUpload.php` | (Future: Phoenix file uploads) | Planned improvement |
| Session management | Phoenix sessions + LiveView | Built-in CSRF protection |

## Future Enhancements

1. **Image Upload**: Implement Phoenix file uploads for component images
2. **Category Management UI**: Add/edit/delete categories through the web interface
3. **Bulk Operations**: Import/export components via CSV
4. **API Endpoints**: REST API for external integrations
5. **User Management**: Multi-user support with roles and permissions
6. **Advanced Search**: Filters by category, stock level, etc.
7. **Barcode/QR Codes**: Generate and scan codes for quick inventory updates

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