Collections/DEVELOPMENT.md

# LocalWeb Development Environment Guide

## Overview

This document describes the LocalWeb Collections PHP MVC application development environment setup using LXC containers.

## Architecture

### Host Environment
- **Location**: `/home/edwin/Documents/Projects/localweb/`
- **User**: `edwin`
- **Container Runtime**: Incus/LXC
- **Container Name**: `www`

### LXC Container `www`
- **OS**: Linux distribution with Apache2 + PHP
- **Web Root**: `/var/www/localhost/` (mounted from host project directory)
- **Service**: `apache2.service` (running as systemd service)
- **Database**: SQLite (`collections.sqlite`)
- **PHP Version**: Compatible with Composer dependencies

### Network Setup
- **LXC Proxy**: Container port 80 → Host port 80
- **Access**: `http://localhost` on host serves the webapp
- **Internal**: Apache binds to `127.0.0.1:80` inside container

## Project Structure

```
/home/edwin/Documents/Projects/localweb/
├── src/                    # PHP MVC source code
│   ├── Controllers/        # Route handlers
│   ├── Models/            # Data models
│   └── Services/          # Business logic
├── templates/             # Twig templates
├── public/                # Web root (entry point)
├── vendor/                # Composer dependencies
├── collections.sqlite     # SQLite database
└── config.php            # Configuration
```

## Development Workflow

### 1. Local Development
- Edit files in `/home/edwin/Documents/Projects/localweb/`
- Changes are immediately reflected in the container via shared mount
- Test via `curl localhost` or browser at `http://localhost`

### 2. Container Management
```bash
# Execute commands in container
incus exec www -- <command>

# Check Apache status
incus exec www -- systemctl status apache2

# View Apache logs
incus exec www -- tail -f /var/log/apache2/error.log

# Reload Apache
incus exec www -- systemctl reload apache2

# Check PHP version
incus exec www -- php -v
```

### 3. Database Operations
```bash
# Access database in container
incus exec www -- sqlite3 /var/www/localhost/collections.sqlite

# Check database permissions
incus exec www -- ls -la /var/www/localhost/collections.sqlite
```

## Application Details

### Technology Stack
- **PHP**: MVC application with PSR-4 autoloading
- **Framework**: Custom MVC with FastRoute routing
- **Templating**: Twig templates
- **Database**: SQLite with PDO
- **Frontend**: Bootstrap 5 + vanilla JavaScript (SPA-like)
- **Dependencies**: Managed via Composer

### Key Features
- **Collections Management**: CRUD operations for items
- **Categories**: Hierarchical category structure
- **QR Codes**: Automatic generation for items
- **Multi-language**: Dutch/English support
- **Search & Filter**: Dynamic content loading

### Routing
- **Web Routes**: Full page loads (`/`, `/categories`, `/parts`)
- **API Routes**: AJAX endpoints (`/api/items`, `/api/categories`)
- **Entry Point**: `public/index.php`

## Development Commands

### Dependencies
```bash
# Install/update dependencies
composer install
composer update

# Check for security issues
composer audit
```

### Testing
```bash
# Manual testing via curl
curl localhost
curl -s localhost | grep -i "collections"

# Test specific endpoints
curl localhost/api/items
curl localhost/api/categories
```

### Debugging
```bash
# Check Apache error logs
incus exec www -- tail -f /var/log/apache2/error.log

# Check access logs
incus exec www -- tail -f /var/log/apache2/access.log

# Verify file permissions
incus exec www -- ls -la /var/www/localhost/
```

## File Permissions

### Container Permissions
- **Project files**: `ubuntu:www-data` ownership
- **Database**: `ubuntu:ubuntu` ownership
- **Apache**: Runs as `www-data` user (group access)

### Common Issues
- Database permission errors: Check `collections.sqlite` ownership
- 403 errors: Verify file permissions in container
- 500 errors: Check Apache error logs

## Environment Variables & Configuration

### PHP Configuration
- Located in container PHP configuration
- Error reporting configured for development
- SQLite extension enabled

### Application Config
- `config.php`: Database path and constants
- `SUPPORTED_LOCALES`: ['en', 'nl'] for i18n
- `DB_PATH`: Points to SQLite database file

## Deployment Notes

### Container Persistence
- Data persists in container filesystem
- Database file stored in project directory
- No external database dependencies

### Backup Strategy
- Git repository for code
- SQLite database backup: `collections.sqlite.backup`
- Regular snapshots of LXC container recommended

## Troubleshooting

### Common Issues
1. **Apache not responding**: Check service status in container
2. **Database errors**: Verify SQLite file permissions
3. **404 errors**: Check `.htaccess` and routing configuration
4. **Permission denied**: Ensure `www-data` can read project files

### Recovery Commands
```bash
# Restart Apache
incus exec www -- systemctl restart apache2

# Fix permissions (if needed)
incus exec www -- chown -R ubuntu:www-data /var/www/localhost/
incus exec www -- chmod -R 755 /var/www/localhost/

# Check container status
incus list
incus info www
```

## Security Considerations

- Container isolation via LXC
- No direct database access from host
- Apache runs with limited privileges
- SQLite database in project directory (not web-exposed)

## Performance Notes

- Lightweight SQLite database
- Minimal PHP dependencies
- Efficient routing with FastRoute
- Client-side caching for static assets