Eventkit 🎪📦

Ein modulares, hochperformantes All-in-One-ERP & Dispositions-System, maßgeschneidert für die Audio/Visual (AV)- und Veranstaltungstechnik-Branche.

Eventkit vereint Bestandsverwaltung (Serialisiert- und Schüttgut), Transportbehälter-Hierarchien, dynamische Event-Disposition mit Zeitausschluss-Garantien, gesetzliche Arbeitssicherheits-Prüfungen (AM-VO / DGUV-V3), Finanzen und Offline-fähiges Lager-Scanning in einem datensouveränen Cloud-Native-System.

---

⚡ Key Highlights & Features

• Sub-Millisekunden Barcode- & RFID-Scanning: Offline-First PWA mit lokaler Command Queue (IndexedDB/Dexie.js) und automatischer Batch-Synchronisation.
• Rechtssichere Compliance & Dynamische Readiness (Österreich AM-VO & DGUV-V3): Strukturierte Messwerterfassung nach OVE EN 50699 & OVE EN 50678 mit 3-Stufen-Prüfung (Dispo-Vorwarnung, Werkstatt-Ticket, Scan-Hard-Gate).
• Systemweite TypeIDs (UUIDv7): Präfixierte, typensichere und zeitlich sortierbare IDs (z. B. ser_..., cas_..., evt_...) mit direktem Cmd + K Universal Entity Inspector.
• Flightcase- & Behälter-Nesting: Parent-Child-Beziehungen für Flightcases, 19"-Racks und Dollies inklusive kaskadierendem LKW-Ladescan und automatischer Ladevolumen-Berechnung (volume_cbm).
• Integriertes Werkstatt- & Taskboard: Automatisierte Ticket-Erstellung bei gemeldeten Schäden (inkl. Fotoupload) oder ablaufenden Prüffristen vor Events.
• Wasm-Plugin-Engine (Wazero): Sandboxed Hot-Reloading für länderspezifische E-Rechnungen (ebInterface, ZUGFeRD / Factur-X) und kundenspezifische Barcode-Parser.
• Entwicklung in Dev Containern: Vollständig isolierte und vorkonfigurierte Container für Backend (Go, Buf, sqlc) und Frontend (Node, pnpm, SolidJS).
• Cloud-Native GitOps: Deklaratives Deployment via Flux CD, CloudNative-PG, Keycloak Operator und KEDA HTTP Add-on (Scale-to-Zero für PR-Vorschauumgebungen).

---

🛠️ Technologie-Stack

Bereich	Technologie	Beschreibung / Rolle
Backend	Go (Golang)	Core-Engine, minimale Latenz, nebenläufige Reservierungsprüfung.
RPC & API	ConnectRPC (@connectrpc/connect)	Typsichere Protobuf-Schnittstellen über HTTP/1.1 & HTTP/2.
Datenbank	PostgreSQL 16+ mit pgx/v5	Logische Schemas (inventory, crm, compliance, workflow, financial, audit), tstzrange.
SQL-Tooling	sqlc	Generiert typsicheren Go-Code direkt aus reinem SQL im Backend (backend/sqlc.yaml).
Frontend	SolidJS / SolidStart	Reaktives UI ohne Virtual DOM Overhead, optimiert für Handhelds.
UI & Routing	TanStack (Query, Router, Table)	Typensicheres Routing, Cache-Synchronisation & virtualisierte Tabellen.
Desktop Client	Tauri (Rust + SolidJS)	Direkter Netzwerkdruck (Zebra ZPL), Multi-Monitor & CAD/MVR-Import.
Auth / SSO	Keycloak (OIDC/OAuth2)	Rollenbasierte Rechteverwaltung (Lager, Crew, Dispo, Admin).
Plugins	Wazero (Pure Go Wasm)	Sichere Wasm-Ausführung mit atomarem Hot-Reloading ohne CGO.
Dev Environment	Dev Containers (Docker)	Isolierte Container-Entwicklungsumgebung für VS Code, Cursor und Antigravity.

---

📁 Repository-Struktur

eventkit/
├── .devcontainer/             # Dev Container Konfiguration
│   ├── docker-compose.yml     # Container-Setup für Backend, Frontend, Postgres, Keycloak
│   ├── backend/
│   │   ├── Dockerfile         # Go 1.22+, Buf, sqlc
│   │   └── devcontainer.json  # VS Code Backend-Konfiguration
│   └── frontend/
│       ├── Dockerfile         # Node 20+, pnpm
│       └── devcontainer.json  # VS Code Frontend-Konfiguration
│
├── README.md                  # Projekt-Dokumentation & Architektur-Referenz
├── AGENTS.md                  # Architektur-Richtlinien und KI-Agent-Regeln
├── buf.gen.yaml               # Buf Schema-Generierung (Go & TypeScript)
├── buf.yaml                   # Buf Modul-Definition
├── docker-compose.yaml        # Standalone Lokale Dev-Services
│
├── proto/                     # Protocol Buffer Definitionen (Single Source of Truth)
│   ├── inventory/v1/          # Barcode-Scan, Modelle, Serialized/Bulk, Container
│   ├── crm/v1/                # Kunden, Locations, Events, Crew-Zuweisung
│   ├── compliance/v1/         # AM-VO / OVE EN 50699 Messprotokolle
│   ├── financial/v1/          # Angebote, Rechnungen, Positionen
│   ├── workflow/v1/           # Taskboard Kanban, Tickets, Kommentare
│   ├── sync/v1/               # Offline-First Batch Synchronisations-Protokoll
│   └── admin/v1/              # Universal Entity Inspector
│
├── backend/                   # Go Backend Core
│   ├── cmd/
│   │   ├── server/            # ConnectRPC API-Server Entrypoint
│   │   └── cron/              # K8s CronJob Runner (Prüffristen, Outbox-Cleanup)
│   ├── internal/
│   │   ├── auth/              # Keycloak JWT Interceptoren & Permission-Guards
│   │   ├── db/                # sqlc generierter Go-Datenbankcode
│   │   ├── ids/               # TypeID (UUIDv7) Parser & Converter
│   │   ├── inventory/         # Bestandsführung, Container-Scans, Buchungs-Gates
│   │   ├── compliance/        # OVE EN 50699 Validierung & Messdaten-Import
│   │   ├── workflow/          # Taskboard- & Reparatur-Logik
│   │   └── plugin/            # Wazero Wasm-Loader & fsnotify Hot-Reloader
│   ├── plugins/               # Wasm-Plugin Quellen & kompilierte .wasm Binaries
│   │   ├── bin/               # Aktive *.wasm Dateien (von fsnotify überwacht)
│   │   ├── einvoice_ebinterface/ # Österreichische ebInterface E-Rechnung
│   │   └── einvoice_zugferd/     # ZUGFeRD / Factur-X XML-Generator
│   ├── sql/
│   │   ├── migrations/        # DDL Up-/Down-Migrationen (golang-migrate)
│   │   └── queries/           # Roh-SQL Abfragen für sqlc
│   ├── sqlc.yaml              # sqlc Konfiguration
│   └── go.mod
│
└── frontend/                  # SolidJS Web- & Scan-PWA
    ├── src/
    │   ├── components/        # Reusable UI Primitives & virtualisierte Tabellen
    │   ├── lib/               # ConnectRPC Client, Dexie.js Offline DB, Audio/Haptics
    │   ├── routes/            # TanStack Router Route-Tree
    │   └── plugins/           # UI Extension-Slot Registry
    ├── package.json
    └── vite.config.ts

---

🏛️ Architektur-Standards & Invarianten

1. Systemweite TypeIDs (UUIDv7)

Jede Entität im Gesamtsystem nutzt typisierte, zeitlich sortierbare Identifikatoren im Format <prefix>_<base32_uuidv7>:

• eqm_ -> inventory.equipment_model
• ser_ -> inventory.serialized_item
• blk_ -> inventory.bulk_stock
• cas_ -> inventory.container (Flightcases, Racks, Dollies)
• loc_ -> inventory.location (Lagerhallen, Gassen, Regale)
• kit_ -> inventory.kit_definition
• mov_ -> inventory.stock_movement
• clg_ -> compliance.electrical_test_log
• tsk_ -> workflow.task
• com_ -> workflow.task_comment
• evt_ -> crm.event
• cli_ -> crm.client
• ven_ -> crm.location (Venues & Spielstätten)
• inv_ -> financial.financial_document
• usr_ -> crm.user
• cmd_ -> sync.offline_command

In PostgreSQL werden TypeIDs zur RAM- und Indexoptimierung als native 128-Bit UUID gespeichert. Die Go-Schicht übernimmt die Konvertierung.

2. Dynamische AM-VO Readiness (Österreich) & Prüfpipeline

Statt eines statischen Sperrflags folgt die Prüfung einer 3-Stufen-Pipeline:

1. Buchungszeitpunkt (Dispo): Dynamischer Abgleich next_electrical_test_due >= event.end_date. Läuft die Frist vor dem Event ab, erfolgt eine weiche Warnung (EXPIRES_BEFORE_EVENT).
2. 14 Tage vor Packdatum: Ein K8s CronJob legt automatisch einen ELECTRICAL_TEST-Task im Taskboard an.
3. Am Packtisch (Barcode-Scan): Hartes Gate CURRENT_DATE <= next_electrical_test_due. Das mobile Scan-Terminal verweigert die Ausgabe ungeprüfter Geräte strikt.

3. Concurrency, Idempotenz & Audit

• Optimistic Locking: Mutationen prüfen WHERE id = $1 AND version = $2 und inkrementieren version = version + 1. Bei Konflikten antwortet das Backend mit HTTP 412 (Precondition Failed).
• Idempotency-Keys: Mutierende ConnectRPC-Aufrufe verlangen einen Idempotency-Key-Header, der transaktional in audit.idempotency_key dedupliziert wird.
• Append-Only Ledger: Jede physische Bestandsänderung wird unveränderlich in inventory.stock_movement protokolliert.

---

📱 Multi-Plattform Client-Matrix

Plattform	Technologie	Zielgruppe	Kernfunktionen
Android MDE	Capacitor / Native Intents	Lager & Laderampe	Zebra DataWedge Laser-Scan, BLE RFID-Pulk-Erfassung, Offline-Queue.
Desktop Office	Tauri (Rust + SolidJS)	Disponenten, PMs	Multi-Window, direkter TCP ZPL-Druck, CAD/MVR-Cache, Cmd+K Palette.
Mobile Web	SolidJS PWA	Techniker, Fahrer	Sign-on-Glass (Lieferschein-Signatur), Kamera-Scan, digitale Call-Sheets.

---

🚀 Entwicklungsumgebung & Schnellstart

Option A: Entwicklung in Dev Containern (Empfohlen)

Für eine saubere, isolierte Umgebung ohne lokale Werkzeuginstallationen (Go, Node, Buf, sqlc):

1. Backend-Container starten:
   • In VS Code / Cursor F1 drücken -> Dev Containers: Open Folder in Container...
   • Ordner .devcontainer/backend auswählen.
   • Der Container startet automatisch mit Go 1.22, Buf CLI, sqlc und verbindet sich mit PostgreSQL und Keycloak.
2. Frontend-Container starten:
   • In einem zweiten IDE-Fenster Dev Containers: Open Folder in Container... aufrufen.
   • Ordner .devcontainer/frontend auswählen.
   • Startet die SolidJS-Entwicklungsumgebung mit Node 20 und pnpm.

Option B: Lokale Entwicklung auf dem Host-System

Voraussetzungen

• Go 1.22+, Node.js 20+ & pnpm
• Docker & Docker Compose
• Buf CLI (brew install bufbuild/buf/buf)
• sqlc (go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest)

# 1. Infrastruktur starten (PostgreSQL, Keycloak, MinIO)
docker compose up -d

# 2. Schemas & DB-Code generieren
buf generate
cd backend && sqlc generate && cd ..

# 3. Backend starten (Port 8080)
cd backend && go run cmd/server/main.go

# 4. Frontend starten (Port 3000)
cd frontend && pnpm install && pnpm dev

---

📄 Lizenz & Dokumentation

• Detaillierte Spezifikationen & Agent-Regeln: AGENTS.md
• Lizenz: Proprietary / Alle Rechte vorbehalten