initial checkin

2026-09-29 09:40:32 +00:00
commit 50b7ccd65f
34 changed files with 11874 additions and 0 deletions
@@ -0,0 +1,98 @@
+# 24HRS Messe-Lotse — Executive Summary
+
+**Date:** 2026-06-10 | **Status:** Planned | **Team:** AI-only execution
+
+---
+
+## The Product
+
+A multi-user web application for managing trade fair booth projects. Replaces the current single-page prototype (`index.html`) with a production system backed by Pimcore, featuring AI-powered document processing, resource planning, and 3D booth generation. Scale: ~300 jobs/year, peaks at 113 jobs per fair.
+
+---
+
+## Delivery Strategy: 6 Vertical Slices
+
+Each slice delivers a complete, independently shippable user capability. No slice waits on a later slice.
+
+```
+ ┌────────────┐    ┌────────────┐    ┌────────────┐
+ │  Slice 1   │───▶│  Slice 2   │───▶│  Slice 3   │   ← MVP: full trade fair
+ │    Messe   │    │    Jobs    │    │  Workflow  │       management system
+ └────────────┘    └────────────┘    └────────────┘
+                                                        
+ ┌────────────┐    ┌────────────┐    ┌────────────┐
+ │  Slice 4   │    │  Slice 5   │    │  Slice 6   │   ← Intelligence &
+ │ AI Skills  │    │ Resources  │    │ 3D Booth   │       automation layers
+ └────────────┘    └────────────┘    └────────────┘
+```
+
+| Slice | Capability Delivered | Value |
+|---|---|---|
+| **1. Messe** | Login, create venues, customers, and trade fairs; dashboard with fair list | Proves entire stack works; first visible UI |
+| **2. Jobs** | Create booth projects linked to fairs/customers; master data editing; file upload via Pimcore DAM | Core entity relationships operational; replaces spreadsheet tracking |
+| **3. Workflow** | All 8 tabs, 8-state workflow (Angebot→Abgeschlossen), Gotenberg PDF export, calendar view | Complete replacement of the index.html prototype |
+| **4. AI Skills** | 12 AI skills process uploaded documents — extract contacts, deadlines, budgets, materials; generate checklist items; detect brand consistency | Eliminates manual data entry from briefing documents |
+| **5. Resources** | Worker, vehicle, equipment, accommodation pools with demand/assignment gap analysis; travel management | Replaces ad-hoc team/vehicle lists with structured resource planning |
+| **6. 3D Booth** | One-click 3D booth model generation via SketchUp + Aluvision; PNG preview + BOM returned to job | Automated design pipeline from job data to production model |
+
+---
+
+## Architecture at a Glance
+
+```
+┌──────────────┐     ┌─────────────────┐     ┌──────────────┐
+│  React SPA   │────▶│  Pimcore REST   │────▶│   MySQL DB   │
+│  (TypeScript)│     │  API (OAuth2)   │     │              │
+└──────────────┘     └────────┬────────┘     └──────────────┘
+                              │
+                    ┌─────────┼─────────┐
+                    │                   │
+              ┌─────▼─────┐    ┌───────▼──────┐
+              │  Gotenberg │    │ Symfony      │
+              │  (PDF)     │    │ Workflow     │
+              └───────────┘    └──────────────┘
+```
+
+- 4-entity data model: FairLocation → Fair → Job ← Customer
+- 4 user roles: Admin, Editor, Viewer, Customer
+- File storage: Pimcore DAM (not localStorage base64)
+- AI skills: Symfony Messenger queue with parallel workers
+
+---
+
+## Key Decisions
+
+| Decision | Rationale |
+|---|---|
+| Vertical slices over sequential phases | AI requires small, verifiable increments; each slice independently shippable |
+| Admin workflow override (`force=true`) | Real-world fair prep is messy; guards alone insufficient |
+| Async 3D generation via message queue | SketchUp cannot handle sync HTTP from web controllers |
+| Tiered document model with graceful fallback | Customer/fair/job-scoped docs, but zero-config for customers without brandbooks |
+| LLM cost investigation before Slice 4 | 10,000+ calls/year needs cost modeling before commitment |
+
+---
+
+## Resource Pool (Slice 5) — Justification
+
+The modeling of 11 resource entities is driven by real scale: CFC2026 alone has 113 booths across 113 customers at one fair, requiring coordinated worker (Barista, Rigger, Driver, etc.), vehicle, equipment, accommodation, and travel planning. A simple text field on the job entity would not support fair-level gap analysis.
+
+---
+
+## Risks & Open Items
+
+| Risk | Status | Mitigation |
+|---|---|---|
+| LLM operational cost may exceed budget | ⚠️ Investigation required | Defer non-critical skills if cost prohibitive |
+| SketchUp must be running for 3D generation | ⚠️ Accepted | Health monitoring + alerting; Slice 6 is optional nice-to-have |
+| AI-only code quality | ⚠️ Managed | Every slice ships with Playwright E2E tests; quality gate = test pass |
+| Workflow guard rigidity vs real-world entropy | 🔬 Investigation | Admin force transition implemented (Slice 3); guard strategy under review |
+
+---
+
+## Timeline
+
+AI-only execution. Slices 1-3 form the MVP and can be verified independently. Slices 4-6 add intelligence and automation on top of the stable core. No external team dependencies; no developer hiring required.
+
+---
+
+*Related: [architecture-vertical-slices-1.0.md](architecture-vertical-slices-1.0.md) (full implementation plan, 368 lines, 100+ tasks)*