Busflow: Master Product Architecture & Business Rules Specification

Product Philosophy:

• Journey-First Development: Every new product feature must be accompanied by at least one primary user journey.
• KISS (Keep It Simple, Stupid): Interfaces must be clean, minimizing cognitive load.
• Opinionated Design: The system dictates the most efficient workflow rather than offering too many confusing choices.
• High Signal-to-Noise Ratio: Users should only see what requires their immediate attention or action.

---

1. AI Product & Inventory Engine

Business Rules: Costing & § 25 UStG Compliance

To ensure exact margin calculation and legal compliance, the Dynamic Margin Calculator strictly bifurcates costs into own operating costs (Eigenleistungen, subject to standard VAT) and third-party procurement (Fremdleistungen).

• Costing Variables:
  • Fixed Costs: Driver daily rates, vehicle depreciation (AFA), insurance premiums, and parking fees.
  • Variable Costs: Diesel consumption per projected kilometer and projected toll fees.
  • Dead Mileage (Leerkilometer): Empty positioning runs and their associated toll segments are explicitly calculated, as they critically impact geographic taxation and overall profitability.
• Geospatial Tax Routing: The tax engine dynamically splits margins for cross-border travel, automatically bifurcating the margin into a taxable portion and an exempt portion as legally required by § 25 Abs. 2 UStG.

UX: Document Parsing (The "Magic Wizard")

Instead of a cluttered split-screen, data ingestion forces an opinionated, step-by-step Wizard interface. Cognitive load is kept to an absolute minimum through strict traffic-light color coding of the extracted fields:

• Red: Missing data (Hard block, user must input).
• Orange: Low confidence data (User must review and confirm).
• Green / Standard: Normal, high-confidence data.

Business Rules: Transport-Agnostic Seat Configurator

The underlying data model is built to be flexible enough for buses, vans, or future transport types.

• Booking Widget Display: The primary focus is presenting a clean seat selection UI to the end-user. It relies on a "Special Seats" category system where seats are assigned custom labels and icons.
• Toggleable Behaviors:
  • Manual Selection (e.g., "Extra Leg Room"): Can be chosen by the user during checkout.
  • Staff Assignment (e.g., "Wheelchair Space"): Disabled for user selection; serves as a placeholder for dispatchers to manage post-booking.
• [FUTURE] Layout Editor: The visual drag-and-drop editor for operators is deferred. Initially, platform admins will create the baseline layouts in the backend to ensure a controlled, high-quality setup.

---

2. Smart Dispatch & Operations Control

Business Rules: EU Compliance Engine (Rule-Based)

The DACH Compliance Copilot rigorously evaluates a simplified 11-hour daily rest heuristic. Full EU Regulation 561/2006 compliance (which requires tracking fortnightly limits, split rests, and integrating digital tachograph data) requires a complex duration-based DutyActivity model that is explicitly deferred to Phase 2.

• Edge Cases: The system automatically accounts for complex rules, such as Doppelbesatzung (multi-driver trips), legally adjusting the regular 11-hour daily rest requirement down to 9 hours.
• Visual Dispatch Signals: Compliance is instantly readable via a 4-color indicator on the dispatcher board:
  • ⚪ Grey: Unassigned / Neutral.
  • 🟢 Green: Fully compliant.
  • 🟠 Orange: Approaching limits (Soft Warning).
  • 🔴 Red: Violation of legal limits (Hard Block).

UX: The Dispatch Board

An opinionated Gantt chart defaulting to a 2-week horizon. Constraints are aggressively distinguished to maintain the signal-to-noise ratio:

• Soft Warnings (Orange/Yellow): Assignable risks (e.g., preference mismatches). Can be overridden.
• Hard Blocks (Red): Visually indicated with thick red borders, completely disabling the assignment button for legal or physical impossibilities (e.g., overlapping shifts, rest violations).

Business Rules: Disruption Protocol

• 1-Tap Incident Reporting: Drivers use the app to drop a GPS pin, upload photos, and generate a categorized incident (BREAKDOWN, DELAY, or PASSENGER_ISSUE).
• Rapid Reassignment: To preserve the routing chain, the dispatcher can drag-and-drop passengers or boarding points onto a replacement vehicle, automatically remapping the booking ties.
• Automated Comms: Disruption triggers feed directly into the communication engine (see CRM section).

---

3. CRM & Automated Communications

UX: Omnichannel Inbox & Offline Fallbacks

• The Inbox: Merges the familiarity of a modern chat app UI (WhatsApp/Email threads) with the robust backend of a traditional ticketing system (Open, Snooze, Resolved).
• Offline Bookings: Provides a streamlined, rapid-entry form for phone bookings requiring minimal strict database mandates (First Name, Last Name) while supporting traditional workflows (cash-on-bus, manual bank transfers).

Business Rules: Configurable Trigger Lifecycles

The system includes a baseline set of automated communication triggers that operators can heavily configure, toggle, or customize:

1. BOOKING_CONFIRMED: Contract/AGB and deposit confirmation.
2. FINAL_PAYMENT_DUE: Automated dunning / Pay Later reminders.
3. PRE_TRIP_REMINDER: T-24 hours prep (departure time, boarding point).
4. INCIDENT_BROADCAST: Automated live delay/breakdown alerts fed from the Disruption Protocol.
5. BOOKING_COMPLETED: Post-trip review generation.

---

4. Executive Command Center & Accounting

UX: Action-First Management Dashboard

The executive view is designed as a high-urgency Command Center, prioritizing operations over historical data to ensure a pristine signal-to-noise ratio.

• Tier 1: Immediate Action Items (Proactive & Reactive)
  • Actual Alerts: Live crises (Breakdowns, extreme delays).
  • Proactive Alerts: AI-driven warnings (e.g., "Traffic delay on Route A threatens driver rest time compliance in 2 hours").
• Tier 2: Current Operations
  • Active/Starting Trips: Live status of vehicles currently on the road.
  • Newest Bookings: A quick feed of incoming revenue.
• Tier 3: Future Opportunities (Resource Gaps)
  • Load Gaps: Flagging under-utilized trips, idle buses, and available drivers to optimize future scheduling and accommodate leave requests.
• Tier 4: Financial Snapshot (Secondary Navigation)
  • Historical cost/profit metrics and future financial projections are tucked into a secondary view to keep the main dashboard actionable.

Business Rules: Accounting Exports & DATEV

Busflow operates as an operational subledger (Nebenbuch). It guarantees a flawless, GoBD-compliant manual file export as the primary accounting handover, preventing operators from being locked out of traditional workflows.

• SKR03/SKR04 Mapping: The export natively maps margin taxation for third-party services (Fremdleistungen). In SKR03, this maps to accounts 3220, 8191, and 8193 (and equivalent SKR04 accounts).
• Cancellations (Storno): The system strictly enforces GoBD compliance. It never overwrites an invoice; it issues a counter-document (Stornorechnung).