🦉 CrumbForest Scanner - Native LAMP Edition

v1.0-RC2 - Production-ready mit Cable Management, Asset Dashboard 2.0 & IPCalc HUD!

🥖 Was ist CrumbForest?

Ein schlankes Barcode-Scanner-System für Hardware-Inventarisierung im Rechenzentrum. Scanne Seriennummern, erfasse Assets und synchronisiere mit Netbox - alles mit dem Smartphone!

Naked LAMP Ansatz: Kein Docker, keine Container - pure Apache + MariaDB + PHP für maximale Transparenz.

⚙️ Tech Stack

  • Backend: PHP 8.5+ (Native LAMP, strict types)
  • Database: MySQL/MariaDB (native, kein SQLite)
  • Frontend: Vanilla JavaScript (zero build step)
  • Testing: PHPUnit 10.5 (Unit + Integration)
  • Coverage: Xdebug 3.5.0
  • Scanner: Html5-QRCode für mobile Kamera
  • Integration: Netbox API für Asset Management
  • Optional: Ollama + Qdrant für AI-Chat (extern/offline)

🚀 Quick Start

macOS (M4 Apple Silicon)

# 1. Automated Setup (empfohlen)
./macos-setup.sh

# 2. Manual Setup
# Siehe SETUP_MACOS.md für Details

# 3. Datenbank erstellen
mysql -u root -p
CREATE DATABASE crumbforest CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE crumbforest_test CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-- (siehe SETUP_MACOS.md für komplette SQL)

# 4. Schema importieren
mysql -u crumbforest_user -pcrumbforest2024 crumbforest < crumbforest_sql/schema.sql

# 5. Dependencies installieren
composer install

# 6. Apache konfigurieren & starten
# Siehe SETUP_MACOS.md Abschnitt 5
brew services start httpd

# 7. Tests ausführen
./vendor/bin/phpunit

# 8. Öffnen
open http://localhost:8080

Linux

# 1. LAMP Stack installieren
sudo apt-get install apache2 mariadb-server php libapache2-mod-php php-mysql

# 2. Datenbank + Schema (wie oben)

# 3. Apache VirtualHost konfigurieren
# DocumentRoot auf web_root/ zeigen
sudo a2enmod rewrite
sudo systemctl restart apache2

📱 Features

  • 📷 Mobile Scanner - QR/Barcode mit Smartphone-Kamera
  • 🏢 Hierarchisches Inventar - Cluster → Rack → Server → Komponenten
  • 📊 Dashboard - Statistiken und Übersicht
  • 🔄 Netbox Sync - Automatischer Export zu Netbox
  • 🤖 AI Chat - Optionaler Assistent (Ollama + Qdrant)
  • 📝 Asset History - Lifecycle-Tracking aller Änderungen
  • 🧪 PHPUnit Tests - 28 Tests (Unit + Integration)
  • 📊 Code Coverage - Xdebug Reports
  • 🩺 Doktor Script - Integrierte Dev-Tools

🧪 Testing

# Alle Tests
./vendor/bin/phpunit

# Nur Unit Tests (schnell, keine DB)
./vendor/bin/phpunit --testsuite Unit

# Nur Integration Tests (mit DB)
./vendor/bin/phpunit --testsuite Integration

# Mit Code Coverage
./vendor/bin/phpunit --coverage-html coverage/
open coverage/index.html

Test-Status:
- ✅ 19 Unit Tests (Config, Auth, JWT)
- ✅ 9 Integration Tests (Login, DB, API)
- ✅ 80 Assertions
- ✅ Code Coverage: 36.23% (Config: 95%, Auth: 77%)

🩺 Doktor Script

Integrierte Dev-Tools für alle Bereiche:

./doktor-crumbforest.sh

# Funktionen:
1) Git Workstation    - Git Commands & Health Check
2) API Tools         - Login, Endpoints, Token Management
3) MySQL Doktor      - DB Status, Queries, Backup
4) PHP & Tests       - PHPUnit, Coverage, Composer
5) Apache Status     - Service Check & Logs
6) System Info       - Hardware & OS Info
7) Qdrant/Ollama     - AI Stack (optional)

🦉 Krümelsprache

Alle wichtigen Code-Dateien haben Krümelsprache-Dokumentation:
- 🦉 Emojis für Sections
- 🥖 "Merksätze" zur Erklärung
- 📋 Kurze, prägnante Kommentare
- Freundlich und einprägsam

📂 Struktur

crumbforest_naked_scanner/
├── web_root/                    # Apache DocumentRoot
│   ├── api/index.php            # REST API Router
│   ├── includes/                # PHP Classes (PSR-4)
│   │   ├── Auth/Auth.php        # JWT + Session
│   │   ├── Config/Config.php    # .env Loader
│   │   ├── Database/Database.php # PDO Wrapper
│   │   ├── Services/            # Business Logic
│   │   └── Integration/         # Netbox Client
│   └── public/                  # Frontend
│       ├── index.html           # SPA
│       └── js/app.js
├── tests/                       # PHPUnit Tests
│   ├── Unit/                    # Isolierte Tests
│   └── Integration/             # DB + API Tests
├── crumbforest_sql/
│   └── schema.sql               # MySQL Schema (bcrypt)
├── composer.json                # Dependencies + PSR-4
├── phpunit.xml                  # Test Config
├── .env                         # Config (nicht committen!)
├── doktor-crumbforest.sh        # Dev Tools
├── macos-setup.sh               # Quick Setup
├── CLAUDE.md                    # AI Assistant Guide
└── SETUP_MACOS.md               # Detailed Setup

🔐 Sicherheit

  • HTTPS: Erforderlich für Kamera-Zugriff (Production)
  • JWT: Token-basierte Authentication
  • bcrypt: Password Hashing (cost factor 12)
  • PDO: Prepared Statements (SQL Injection geschützt)
  • RBAC: Role-based Access (Admin vs User)
  • .env: Secrets außerhalb von web_root
  • 600 Permissions: Für .env in Production

🎯 Design Philosophy: "Naked"

bash → php → mysql → backend → vanilla → simple → export

  1. bash first: Setup via Shell Scripts
  2. php: Native PHP 8.5+, no frameworks
  3. mysql: Direct MariaDB, no ORM
  4. backend: API-first, single router
  5. vanilla: Zero build process
  6. simple: No Docker, no abstraction layers
  7. export: Netbox sync as goal

Warum "Naked"?
- ✅ Maximum transparency (see every part)
- ✅ Zero hidden magic
- ✅ Traditional LAMP deployment
- ✅ Perfect for RZ/datacenter environments
- ✅ Easy debugging & maintenance

📚 Dokumentation

  • CLAUDE.md - Guide für Claude Code (AI Assistant)
  • SETUP_MACOS.md - Komplette macOS M4 Installation
  • tests/README.md - Test-Dokumentation
  • DEPLOYMENT.md - Production Deployment (Linux)

🔑 Default Credentials

Nach Schema-Import:

Username: admin
Password: crumbforest2024

⚠️ WICHTIG: Passwort nach erstem Login ändern!

🛠️ Development

# Code linting
find web_root/includes -name "*.php" -exec php -l {} \;

# Autoloader regenerieren
composer dump-autoload -o

# Dependencies updaten
composer update

# Neuen Test erstellen
cp tests/Unit/ConfigTest.php tests/Unit/MyTest.php

🐛 Troubleshooting

# Database Connection Failed
mysql -u crumbforest_user -pcrumbforest2024 crumbforest -e "SELECT 1;"

# Class not found
composer dump-autoload -o

# Apache läuft nicht
brew services restart httpd  # macOS
sudo systemctl restart apache2  # Linux

# Tests schlagen fehl
./vendor/bin/phpunit --testdox

🤝 Contributing

  1. Tests schreiben für neue Features
  2. Krümelsprache-Kommentare hinzufügen
  3. Code Coverage > 70% halten
  4. "Naked" Philosophy respektieren (no frameworks!)

📄 Lizenz

Internes Projekt - Keine öffentliche Lizenz

📈 Roadmap (v1.0 Final)

  • [ ] Tests: Erhöhung der Test Coverage (Backend Models, Cable Logic)
  • [ ] Cosmetics: UI Polish (Animations, Transitions, dark-mode refinement)
  • [ ] Consistency: Einheitliche Error Messages & Toasts

🙏 Credits

Erstellt mit viel ☕ und 🥖 für effiziente RZ-Verwaltung!

Special Thanks:
- Gemini (Antigravity) & CrumbForest Crew - Co-Pilot & Lead Architect (RC2)
- Claude Code - Initial Base & AI-gestütztes Development
- pepperPHP Community - Naked PHP Philosophy
- Homebrew - macOS Package Management

CrumbForest Scanner - Native LAMP Edition
Version: v1.0-RC2
Build: 2025-12-22
PHP: 8.5.0+ | MariaDB: 12.1.2+ | Xdebug: 3.5.0

🦉 Der Wald atmet. Die Eule testet. M4 läuft.