Documentation TODOs

This document tracks identified gaps in the project documentation that need to be addressed. It is divided into Product & Domain missing details and Technical & Architecture missing details.

1. Product & Domain Specifications

• [Medium Priority] State Machines & Lifecycles:

  • Context: The domain-model.md provides a high-level summary but lacks exact state machines.
  • Action: Document specific statuses for a Booking (e.g., draft, deposit_paid, fully_paid, cancelled), a Trip, and a Ticket. (Completed: Booking state machine in L3 level-3-domain-2-booking-state-machine.md, ServiceLeg state machine in L3 level-3-domain-3-serviceleg-state-machine.md, Ticket lifecycle in event-contracts-commerce.md)

• [High Priority] Pricing Engine & Margin Rules:

  • Context: An important gap requiring further research and customer interviews.
  • Action: Document the exact mathematical rules for the "Dynamic Margin Calculator", discount priorities (e.g., early-bird vs. group), and DACH-specific tax handling (e.g., VAT rules for international travel).

• [Medium Priority] Trigger-Based Messaging Logic:

  • Context: Automated messaging is mentioned, but exact triggers and fallback logic are missing. The Communications architecture (architecture/communications.md) establishes the structural foundation but lacks operational detail.
  • Action: Map out all system events that trigger communications (e.g., T-24 hours), specify the channels used, and define fallback mechanisms (e.g., if a passenger has no WhatsApp). (Completed: Full 22-entry trigger_event registry in notification-pipeline-protocol.md §7, fallback chain in §6)

• [Medium Priority] Communications Architecture — Remaining Sections:

  • Context: architecture/communications.md has been created with an overview and workflow integration, but several sections are placeholder TODOs.
  • Action: Document: (1) per-tenant channel provisioning flow, (2) full message delivery pipeline (template → render → dispatch → tracking), (3) real-time inbox architecture (WebSocket/subscriptions, agent assignment, conversation routing), (4) communications-specific observability dashboards and alerting. (Completed: (1) channel-provisioning-protocol.md, (2) notification-pipeline-protocol.md, (3) inbox-protocol.md, (4) observability in communications.md §Observability)

• [High Priority] Copilot & AI Assistant Specifications:

  • Context: docs/architecture/ai.md details the infrastructure, but there are no concrete product specifications or user flows for how the user actually interacts with these AI features in the UI.
  • Action: Define UX/UI flows, trigger points, and failure states for specific AI features (e.g., Customer Support Copilot, Dispatch Assistant).

• [High Priority] Permissions and Roles Matrix (RBAC):

  • Context: docs/architecture/roles.md exists, but there is no detailed product specification outlining exact permission tiers.
  • Action: Document a detailed RBAC matrix specifying read/write access for different roles (e.g., Dispatcher, Manager, Accounting) within the workspace app.

• [Medium Priority] Post-Booking Passenger Modifications:

  • Context: The B2C passenger journey covers the initial booking, but the logic for modifying an existing booking is not documented.
  • Action: Document the user flows and business rules for post-booking modifications (e.g., adding luggage, changing a boarding point, cancellations) via the passenger portal.

• [Medium Priority] SaaS Subscription & Pricing Tiers Logic:

  • Context: While the Lago billing engine is specified in PRODUCT_payments-and-billing.md, the exact details for SaaS subscription tiers, Free Trial logic, feature gating, and more remain undefined.
  • Action: Document the specific subscription tiers (e.g., Free, Pro, Enterprise), what features are restricted per tier, how the Free Trial logic operates (duration, transitions, limits), and how these limits map to Lago's metered usage configuration.

2. Technical & Architecture Details

• [High Priority] Concrete Database Schema (ERD):

  • Context: A logical next step following the extensive work on the domain model. database.md explains the strategy but lacks concrete definitions.
  • Action: Create an Entity-Relationship Diagram (ERD) and define table schemas for core entities (Operator, User, Tour, Trip, Booking, etc.). (Completed: Separated into schema-backoffice.md, schema-commerce.md, schema-operations.md, schema-communications.md and linked in database.md)

• [High Priority] Authentication & "Magic Link" Flows:

  • Context: Specific auth flows for passengers (Magic Link), B2B agents, and internal Dispatchers need definition.
  • Action: Create a centralized authentication concept document. This document should remain general, linking out to specific implementation areas and external docs (like Nhost Auth), rather than repeating low-level details.

• [High Priority] Dispatch Board Blocking Schema Gaps:

  • Context: The level-1-domain-6-product.md analysis discovered 4 critical missing entities that block the Dispatch Board MVP: Vehicle Maintenance, Crew Absences, Crew Qualifications, and Sub-contracting.
  • Action: (Completed: Schemas for vehicle_inspections, crew_absences, crew_qualifications defined in Backoffice; leg_assignments updated for sub-contracting in Operations. ADR-007 and ADR-008 approved.)

• [Medium Priority] Offline Sync & Conflict Resolution Concept:

  • Context: The offline-first capability of the Driver App lacks technical documentation.
  • Action: Document the offline sync strategy (e.g., local state to Hasura/Postgres sync, conflict resolution if multiple drivers modify data).
  • Location: Add the specific implementation document directly to the apps/driver/docs/ directory, and link to it from the relevant root-level conceptual docs. (Completed: offline-sync-protocol.md created with full conflict resolution matrix)

• [Medium Priority] Event-Driven Architecture (EDA) & Queues Review:

  • Context: Existing docs mention Hasura Events → Redis → Nest.js workers. The strategy maintains the use of Redis and BullMQ for the event-driven architecture and background jobs.
  • Action: Document the finalized event-driven architecture using Redis and BullMQ. (Completed: workflow-orchestration.md fully specifies Hasura ET → BullMQ → NestJS patterns. Event catalog documents 53 events with triggers and consumers.)

• [High Priority] L3-5.2.2 Secrets Management Architect Loop:

  • Context: All five L3 Domain 5 architect loops (5.1.1–5.2.1) reference L3-5.2.2 for Docker Secret wiring, DSN provisioning, and rotation.
  • Action: (Completed: architect loop executed and hardened into ADR-029, secrets-rotation-runbook.md, and the .github/workflows/secrets-sync.yml stub. Drilldown + per-loop notes archived under supporting/reviews/archive/.)

• [High Priority] Domain 5 / L3 Architect-Loop Roll-up:

  • Context: Six drill-downs (L3-5.1.1 … L3-5.2.2) covering Ubicloud Postgres cutover, Swarm quorum topology, LB strategy, manager SSH host-key rotation, LGTM observability, backup verification, pg_cron TTL retention, and secrets management.
  • Action: (Completed: cascaded into infrastructure.md §5/§6 + §6.2, observability.md, gdpr-strategy.md §1/§4, ADR-022 – ADR-029, seven protocol runbooks in docs/protocols/, skeleton implementation stubs in terraform/modules/postgres-ubicloud/, docker/observability/, and .github/workflows/, and deferred migration DDL in docs/supporting/plans/gdpr-migration-plan.md + docs/supporting/plans/tenant-credentials-encryption-plan.md (kept out of apps/hasura/migrations/ until target schemas exist). Source drilldown + per-loop artifacts archived under supporting/reviews/archive/.)

• [High Priority] Domain 5 / L3 Infra Wiring Follow-ups (before first production deploy):

  Items below are deliberately carved out of the "Ready to Code" Domain 5 roll-up because they require secrets or GitHub-side configuration that cannot be checked into the repo. They must land before the two new workflows (.github/workflows/backup-verify.yml, .github/workflows/secrets-sync.yml) are allowed to fire against production. Both workflows are in the repo and safe today — secrets-sync.yml is workflow_dispatch-only and backup-verify.yml will simply fail loudly on the cron if secrets are absent — but leaving these items undone means the first scheduled backup-verify run will page #ops at 03:00 UTC.

  A. backup-verify.yml open items (triage reference: backup-verify-runbook.md)

  • GitHub Secrets required:
    • RCLONE_CONFIG — full rclone .conf body with both remotes:
      • hetzner-object-storage: (primary — pg_dump producer target)
      • minio-mirror: (fallback — used when workflow_dispatch input backup_source=minio-fallback is selected)
    • SLACK_OPS_WEBHOOK — incoming-webhook URL for #ops. The workflow auto-detects 4xx on the webhook and warns the operator to rotate.
  • Stub implementation to replace: scripts/verify_soft_fks.py currently returns 0 unconditionally. Needs a real implementation that reads config/backup-verify/soft-fk-allowlist.yaml, sweeps the restored database for orphaned rows in declared soft-FK pairs (messages.booking_id, payments.refund_passenger_id, service_leg_overrides.leg_id), and fails (non-zero exit) when any pair exceeds its max_orphans tolerance.
  • Cron-until-secrets decision: the workflow is on 0 3 * * *. Options before the secrets land:
    • (a) comment out the schedule: block and rely on workflow_dispatch only until the first dump exists, or
    • (b) leave the cron enabled so the failure surfaces loudly as a Slack alert on day 1 and forces the operator to configure the secrets. Pick explicitly; do not let it drift.
  • Producer contract (separate repo wiring): docker/backup/producer.env declares the assumed pg_dump flags (--format=custom, --jobs=4, extensions pgcrypto,pg_cron,vector,pgsodium, SIZE_MIN_GB=10, SIZE_MAX_FACTOR=2.0, PGSSLMODE=verify-full). The producer is not yet deployed — when it lands (on the Swarm data-tier node running pg_dump against Ubicloud), verify the flags match or bump the workflow's SIZE_MIN_GB / size guard to reality.
  • Trailing-median size guard: currently advisory (see workflow step Size guard). Hydrate the upper bound from Mimir once the backup-producer job emits backup_bytes_total{job="pg_dump_producer"} — runbook F1 has the metrics query.

  B. secrets-sync.yml open items (ADR reference: ADR-029; triage reference: secrets-rotation-runbook.md)

  • GitHub Environment required: create an Environment called production with a required-reviewer protection rule (Julian + one other founder). The jobs.sync.environment.name expression resolves to production when the dispatch input selects it; without the Environment protection rule, anyone with repo-write can push secrets into the live Swarm.

  • GitHub Secrets required (both Environments):

    • PRODUCTION_SWARM_MANAGER_HOSTS — whitespace-separated list of manager public IPs (or DNS names). Populated from the Terraform output of the swarm module. A plain list; one per line is fine.
    • PRODUCTION_MANAGER_HOST_KEYS — concatenated ~/.ssh/known_hosts content covering every manager node, built from the ADR-025 per-manager SSH host keys Terraform output (terraform output -raw manager_host_keys). Never replace this with a StrictHostKeyChecking=no workaround — the CI lint in the repo enforces ADR-025.
    • DEPLOY_SSH_KEY — ED25519 private key authorised in hcloud_ssh_key.nodes for root@ SSH onto the managers.
    • SLACK_OPS_WEBHOOK — same as above (workflow posts the new _v<n+1> logical name only — never the value).

  • First-use / bootstrap sequence: the first real run should dispatch with secret_name = pgexporter_dsn and source_github_secret = PGEXPORTER_DSN_V1 to create pgexporter_dsn_v1 on the managers. Once that exists, lift the replicas: 0 gate on postgres-exporter in docker/docker-compose.observability.yml per alert A8 — the placeholder gate exists specifically because pgexporter_dsn is not populated yet.

  • Cross-repo secrets to sync next: busflow_db_writer, mollie_api_key, whatsapp_360dialog_token. Each dispatch creates a new versioned _v<n+1>; the operator flips services one at a time per the rotation runbook.

  • Rotation cadence: ADR-029 commits to quarterly rotation for provider keys. Schedule the calendar reminders once the first rotation completes, so the cadence starts from a known-good baseline rather than from "workflow exists".

  • Context: Tools currently listed (Stripe, Klarna, HanseMerkur, 360dialog/Twilio, DATEV) were brainstormed and may change (e.g., likely dropping Stripe and Twilio).

  • Action: Review and update the documentation to reflect the finalized stack of third-party integrations, and define the webhooks and API contracts for the ones that remain.

• [Medium Priority] PricingRule & CapacityRule Value Object Specification:

  • Context: The domain-model.md mentions PricingRule and CapacityRule as "Value Objects" but they are not shown in the ER diagram, nor is their storage location specified (JSONB on TourOffering? On CostingSheet? Standalone?).
  • Action: Define the exact structure, storage location, and lifecycle of these value objects. Clarify how they interact with the CostingSheet price matrix generation and whether they are inherited from TourTemplate → TourOffering.

• [Medium Priority] Dev-Process AI Agent Documentation:

  • Context: The "Agentic Development Process" section in ai.md covers SDLC integration at a high level (automated PR reviews, autonomous refactoring, shift-left security), but lacks operational detail. In contrast, product-facing AI (Copilot, Magic Upload, agent pipelines) is thoroughly documented across multiple files.
  • Action: Expand documentation to cover: CI/CD integration of AI code reviews (which tools, how they're triggered), security audit workflow specifics (scan triggers, alert routing), tooling configuration (MCP setup, AgentShield policies), and concrete examples of the dev-agent feedback loop.

• [High Priority] Testing Strategy Specifics (E2E & Offline):

  • Context: docs/architecture/tests.md exists, but lacks details on how E2E testing (Playwright) will handle the offline-first capabilities of the PWA.
  • Action: Document the approach for simulating offline mode and verifying sync mechanisms during E2E tests for the driver app.

• [High Priority] Migration Playbook:

  • Context: The project scope mentions "Zero-Downtime Migration" as a core value pillar, but technical documentation is missing.
  • Action: Detail the data migration pipeline, including extraction strategies from legacy systems (Kuschick/Turista) and transformation mapping to the Busflow PostgreSQL schema.

• [Medium Priority] Disaster Recovery & Backups:

  • Context: infrastructure.md mentions Hetzner Managed Postgres, but disaster recovery plans are undefined.
  • Action: (Completed: backup retention, restore procedures, automated verification pipeline, producer liveness, and SLA-tiered DR drill cadence now documented in infrastructure.md §6.)

• [High Priority] Production Container Resource Limits:

  • Context: docker-compose.production.yml declares zero deploy.resources.limits on any service. A single runaway container triggers the kernel OOM-killer, which can take down Postgres.
  • Action: Profile services under load, then add deploy.resources.limits.memory and deploy.resources.reservations.cpus to every service. See infrastructure.md §5.

• [Medium Priority] Terraform Drift Detection Workflow:

  • Context: terraform.yml only runs terraform plan on PRs touching terraform/**. Manual SSH changes to servers drift silently.
  • Action: Implement .github/workflows/terraform-drift.yml — weekly cron running terraform plan -detailed-exitcode, alerting on exit code 2. See infrastructure.md §5.

• [Medium Priority] Docker System Prune Cron:

  • Context: Every deploy pushes new images but never cleans old ones. Root disk fills within months.
  • Action: Implement weekly docker system prune --all --force --filter "until=168h" on each Swarm node. See infrastructure.md §5. (Completed: docker-pruner global service in docker-compose.infra.yml — runs every Sunday at ~03:00 UTC on all nodes.)

• [Medium Priority] Hasura Metadata Drift Check:

  • Context: deploy.yml applies metadata forward-only via hasura metadata apply, silently overwriting console changes.
  • Action: Add post-deploy hasura metadata diff step to deploy.yml + weekly cron variant. See ci-cd.md §2.

• [Low Priority] Disaster Recovery Drill:

  • Context: Backup verification tests restorability but not the full system rebuild path (env vars, Docker registry auth, DNS, Terraform state).
  • Action: First drill after Ubicloud cutover; cadence escalates with SLA tier (annual → quarterly). See infrastructure.md §6.

• [High Priority] Preview Environment Isolation & Resource Limits:

  • Context: Preview deployments (per PR) run as separate Docker Swarm stacks on the production cluster with no resource constraints. Without limits, previews compete for CPU/RAM with production services and can cause OOM kills.
  • Action: (1) Create docker-compose.preview.yml with deploy.resources.limits (CPU/memory caps per container). (2) Add Swarm placement constraints to pin previews to worker nodes. (3) Implement a concurrency cap (max 3 active previews) in the GitHub Actions workflow. (4) Decide on database strategy: shared DB with schema isolation vs. ephemeral per-preview DB.

• [Medium Priority] API Rate Limiting & Security Policies:

  • Context: Infrastructure docs list Traefik and Hasura, but specific security configurations are missing.
  • Action: Specify rate limiting strategies, Web Application Firewall (WAF) rules, and exact CORS policies to protect public-facing endpoints.

• [Low Priority] Remove --passWithNoTests from @busflow/api Test Script:

  • Context: The apps/api/package.json test script uses jest --passWithNoTests as a temporary workaround to prevent CI failures while no .spec.ts files exist.
  • Action: Once the first test files land in apps/api/src/, revert the script back to "test": "jest" so that accidental test-file deletions surface as CI failures.

3. Documentation Housekeeping

• [Medium Priority] Investigate Documentation Reorganization Potential:

  • Context: As the documentation has grown organically, there may be overlapping content, unclear categorization, or opportunities to consolidate related topics.
  • Action: Audit the current docs/ structure for duplicated content, inconsistent categorization, and navigation pain points. Propose a revised information architecture if warranted.

• [High Priority] Reduce Core Docs Folder Size:

  • Context: The core docs/ folder may contain content that could be moved closer to the code it describes (e.g., into apps/*/docs/ or packages/*/docs/), archived, or consolidated.
  • Action: Inventory all files in the root docs/ directory. Identify candidates for: (1) co-location with their respective app/package, (2) merging into other documents, (3) archiving outdated content. Goal is a drastically leaner core docs folder.

• [High Priority] Identify & Remove Redundant or Obsolete Documentation:

  • Context: Beyond reorganization, some documentation may be outright deletable.
  • Action: Perform a targeted audit to delete obsolete brainstorming notes, duplicated content, and placeholder text specifically. (Completed: Removed 8 old iteration docs and consolidated duplicate architectural text)

4. AI Agent & Tooling Setup

• [Medium Priority] Autonomous Documentation Issue Agent:

  • Context: The project documentation requires continuous maintenance and review to prevent conflicting information and outdated content.
  • Action: Add an autonomous AI agent configured to run daily to scan documentation for inconsistencies (e.g., conflicting information) and automatically create PRs to address identified issues.

• [High Priority] Project AI Agent Setup — Skills, Instructions & Folder Hygiene:

  • Context: The monorepo uses an agentic development workflow (.agents/). Skills, basic instructions, and folder structure need to be validated.
  • Action: (Completed: First round consolidated into .antigravity/. Second round consolidated all AI config into .agents/ — skills, workflows, prompts, and docs. Deleted .antigravity/, .jules/, .pi/, CONTEXT.md. CLAUDE.md reduced to a 3-line pointer. HANDBOOK.md serves as the single centralized entry point.)

• [Medium Priority] Investigate & Decide on Story / Task Management Tool:

  • Context: The monorepo currently lacks a formal in-repo mechanism for tracking stories, tasks, and sprint-level work items beyond this TODO file.
  • Action: Research options for lightweight, repo-native task management (e.g., GitHub Projects, Linear integration, markdown-based tools like todo.md conventions, or issue-linked task files). Evaluate against criteria: developer friction, visibility, integration with CI/PR workflow, and suitability for a small founding team. Recommend and document the chosen approach.

• [Medium Priority] Test NotebookLM Integration & Evaluate Docs Reduction Potential:

  • Context: The NotebookLM MCP server is now connected, enabling AI-assisted querying of curated knowledge notebooks. If key domain or architecture knowledge is reliably accessible through NotebookLM, some of the local docs/ content may become redundant.
  • Action: (1) Exercise the NotebookLM integration end-to-end with real project queries to validate reliability and answer quality. (2) Design a future workflow for when and how NotebookLM should be consulted vs. local docs. (3) Identify specific doc files or sections that could be removed from the repo if their content is adequately covered by a NotebookLM notebook, and document the decision criteria.

• [High Priority] Docs-Hub — Deploy Documentation Portal:

  • Context: The docs-hub (studio/docs-hub) VitePress portal and context-engine (packages/context-engine) RAG server are implemented. The predecessor docs-assistant has been removed.
  • Action: Deploy docs-hub (static VitePress) and context-engine to Hetzner Docker Swarm. Verify end-to-end AI chat, search, and role-based content visibility. → See docs-hub.md for the full specification.

• [Medium Priority] Evaluate Storybook as Replacement for Histoire:

  • Context: Histoire (studio/histoire) is currently used for component documentation. However, Histoire is stuck at 0.17.x — the latest version (1.0.0-beta.1) is unstable, and it only supports Vite 5/6, blocking Vite 8 adoption in the design system.
  • Action: (Resolved: Removed studio/storybook — keep Histoire for now; reassess when Vite 8 compatibility becomes a blocker.)

• [Medium Priority] Add GitHub CODEOWNERS File:

  • Context: The monorepo contains sensitive infrastructure (terraform/, docker/, .github/workflows/, scripts/) alongside product code. Access control and review requirements differ between these areas.
  • Action: Create a .github/CODEOWNERS file restricting approval of infrastructure and CI/CD changes to founders/ops. This provides the security boundary benefit of repo extraction without the multi-repo overhead.

5. Docs, Product & Architecture Refactoring

• [High Priority] Use AI to question EVERYTHING (Comprehensive Review & Refactoring):
  • Motivation: Leverage AI to aggressively challenge and refine the existing documentation, product definitions, and architecture.
  • Approach (Iterative Method):
    • Decomposition: Break down the details systematically (at least in 3 levels: by Domain -> by Subdomain -> by Feature).
    • Multi-Perspective Review: Look at the system from different angles:
      • Bird's Eye View: Overview & how it all works together.
      • Detailed: Detailed research into whether a specific feature makes sense.
      • Abstract: Is the overarching vision sound?
      • Concrete: Do the specific details actually reflect that vision?
    • Targeted Queries: For each decomposed area, ask specific questions for results:
      • What is missing?
      • What needs to be improved?
      • What is superfluous / too much?
      • Is the information in the correct place?
    • Iterate, Iterate, Iterate: Continually refine the documentation based on answers to these queries.
  • Action / Content Guidelines: Heavily use AI to generate clear and concise information. Ensure the documentation adheres to these rules:
    • Be Direct
    • No Redundancy
    • Active Voice
    • Simple Language
    • Keep it Short
    • Focus strictly on Key Points
  • Playbook: Iterative review prompts and execution plan were produced as temporary agent artifacts and are not tracked in docs/.
  • (Completed: Full 4-level iterative review executed across 6 domains. 49 review artifacts produced, 21 ADRs committed, 14 protocols finalized. All domains at "Ready to Code" status.)

6. Deferred Design Decisions (TourDeparture Refactoring)

Items deferred during the TourDeparture entity introduction. Each needs its own design pass before schema inclusion.

• [Medium Priority] ✅ Tour Content Model (Backoffice & Commerce):

  • Resolved: Content lives as a content JSONB column on tour_templates, validated by TourContentSchema in @busflow/types. Structure: { highlights, included_services, excluded_services, travel_requirements, itinerary: ItineraryDay[], cover_image_key, gallery_image_keys }. Per-departure notes use departure_notes TEXT on tour_departures. Commerce projection deferred to the Publish flow milestone. See schema-backoffice.md.

• [Medium Priority] Vehicle & Crew Assignment to TourDeparture:

  • Context: The TourDeparture entity is the natural place to assign vehicles and crew to a scheduled departure. Currently no linking tables exist. Vehicle/crew assignment may need to be per-leg rather than per-departure (e.g., different drivers for different ServiceLegs).
  • Action: Design the assignment model. Key questions: (1) Is assignment per-departure (tour_vehicle_assignments, tour_crew_assignments) or per-ServiceLeg (via LegAssignment in Operations)? (2) If both exist, which is "planned" vs. "actual"? (3) Does this overlap with Operations' existing LegAssignment entity? Coordinate with the Operations schema design.

• [Low Priority] Allotment Linking to TourDeparture:

  • Context: Allotment (reserved hotel rooms, ferry slots) currently links only to Supplier. The CostingSheet implicitly factors allotments via procurement_items[], but there is no explicit TourDeparture → Allotment link showing which inventory blocks are consumed by which departure.
  • Action: Decide whether explicit linking is needed. Key questions: (1) Is the implicit link through CostingSheet.procurement_items[].allotment_id sufficient? (2) Does an explicit junction table (tour_departure_allotments) add value for capacity tracking (Backoffice Review, Strategic Blind Spot #4: "allotment consumption tracking")? (3) Could this be handled as a computed view instead?

• [x] Make sure current system is ready to be localizable & adaptable for other markets (Added: LegalForm entity and default_locale/currency on Operator)

6b. Boarding Points Drilldown — Design Decisions

Items surfaced during the critical review of the Boarding Points drilldown conversion. Each needs a decision before the spec is finalized.

• [High Priority] Boarding Surcharge → Commerce Flow:

  • Resolved: Ancillary-based flow confirmed. Commerce auto-creates a commerce.ancillaries row with type = 'BOARDING_SURCHARGE' (per-passenger, quantity: 1) during submitCheckout. Reuses the existing financial pipeline — appears as an invoice line item, refundable independently. Per-booking flat-rate toggle deferred to SB-9 (ancillary catalog design). Documented in boarding-points.md §Surcharge as Ancillary and schema-commerce.md §ancillaries.

• [Medium Priority] Door Pickup Surcharge: Replaces or Stacks?

  • Resolved: Standalone — each pickup mode (stop or door) carries its own independent surcharge. The passenger pays the door pickup surcharge only, not the stop surcharge on top. Documented in boarding-points.md §Door Pickup Mechanics.

• [Medium Priority] door_pickup_address on Commerce Passengers:

  • Resolved: Added door_pickup_address JSONB ({ formatted_address, lat, lng }) and is_door_pickup BOOLEAN (pickup mode indicator) to commerce.passengers. boarding_point_id always references backoffice.boarding_point_library — no polymorphic FK. Null when passenger selected a regular stop. Documented in schema-commerce.md §passengers and boarding-points.md §Commerce Reference.

• [Medium Priority] checkout_sessions.selected_options Extension:

  • Resolved: selected_options is JSONB — extended the TypeScript interface with is_door_pickup: boolean and door_pickup_address?: { formatted_address, lat, lng }. Documented in boarding-points.md §Checkout Session Integration and schema-commerce.md §checkout_sessions.

• [Medium Priority] max_door_pickups Enforcement in Commerce:

  • Resolved: max_door_pickups lives on the template (smart default: 5, alongside deposit_config and cancellation_policy). Value travels via TripPublished event payload. Commerce counts existing door pickup bookings at checkout time and rejects when the limit is reached. Documented in boarding-points.md §Door Pickup Mechanics.

• [Low Priority] Boarding Point Archive Behavior:

  • Resolved: Same pattern as ancillary catalog archiving. Archived items stay on existing template assignments and historical departures. They disappear from the picker for new assignments. Documented in boarding-points.md §Archive Behavior.

• [Low Priority] Boarding Point Onboarding Seeds:

  • Resolved: No seeds. Boarding points are location-specific — no universal defaults. The Concierge Onboarding wizard prompts "Where is your main departure point?" and creates the first library item from that address. Future: wizard suggests extra stops and door pickup from the departure point ([v0.2]).

• [Low Priority] Departure-Specific Pickup Times + Boarding Order:

  • Context: Both pickup times and boarding order are operational concerns that depend on the finalized passenger list and actual door pickup bookings — not product configuration. Defining a static boarding order at the library level implies a fixed route that ignores real-world booking patterns. The current data model has no place for either.
  • Action: Design the pickup time + boarding order assignment flow as a [v0.2] drilldown. Likely requires a dispatch-side table or computation. Separate from the boarding point library design.

7. Industry Best Practices & Future Gaps (Phase 2+)

These items were identified during the Level 1-3 audits as important industry-standard capabilities that are not yet part of the core "Ready to Code" implementation.

• [High Priority] Bank Statement Import & Auto-Matching:

  • Context: No mechanism for importing MT940/CAMT files to match payments to bookings.
  • Action: Architect bank_imports and bank_transactions tables for automated bookkeeping.

• [High Priority] Partial Refund Flows (Mollie Sync):

  • Context: Explicit mapping between partial booking cancellations and Mollie ledger refunds is missing.

• [High Priority] § 25 UStG Per-Line Tax Split:

  • Context: Mixed tours legally require per-line-item tax treatment (Standard vs. Margin scheme) rather than a global toggle.

• [High Priority] Group Booking Modifications:

  • Context: Securely tracking post-confirmation passenger additions and price adjustments.

• [Medium Priority] Voucher & Gift Card Management:

  • Context: Complex accounting for partial redemptions and refunds of value-based vouchers.

• [Medium Priority] Agency Payouts / Commission Ledgers:

  • Context: Transactional settlements for B2B reseller commissions.

• [Medium Priority] Booking Source Channel:

  • Context: Dispatcher visibility into booking origin (Widget, API, Manual, Phone).

• [Medium Priority] Automated Compliance Checks (VIES/Visa):

  • Context: Real-time validation of EU VAT IDs and passenger visa requirements for manifests.

• [Medium Priority] Multi-currency Bookings & Forex Engine:

  • Context: Separation of source and base currencies in FinancialLedger to handle exchange rate anomalies.

• [Medium Priority] Kalkulations-Engine: FX Rate Refresh & Stale Allotment Alerts:

  • Context: Tracking FX rate staleness and procurement rate changes on LOCKED costing sheets.

• [Medium Priority] JSONB Audit Diffing:

  • Context: Moving from full-blob snapshots to structured sub-events or JSON-patches for audit logs.

• [Low Priority] Dynamic Booking Questions:

  • Context: Configurable data collection (passport numbers, etc.) during the checkout flow.

• [Low Priority] Partial Recalculation (Dirty-Flag Engine):

  • Context: Performance optimization for the Pricing Engine using selective dirty-flag propagation.

• [Medium Priority] Bus Hardware Integration & Telematics:

  • Context: The current TelemetryPoint entity assumes GPS/speed/fuel data from hardware on the bus, but Phase 1 has no hardware integration. Telematics hardware (OBD-II dongles, GPS trackers, dashcams) could enable live ETA tracking ("Where is my Bus?"), fuel monitoring, digital tachograph data import (EU-561 compliance), and route deviation alerts. This is a significant differentiator for Pillar 3 but requires vendor evaluation, hardware provisioning logistics, and a dedicated real-time data ingestion pipeline (separate from the offline mutation sync protocol).
  • Action: Research: (1) available telematics hardware for DACH bus fleets (e.g., Geotab, Samsara, TomTom Telematics, Webfleet), (2) whether to use a third-party telematics platform or build a lightweight ingestion API, (3) cost model (per-vehicle hardware + SaaS fee vs. one-time OBD-II dongle), (4) fallback option using the driver's phone GPS via PWA Geolocation API for Phase 1 ETA tracking. Define scope boundaries: what's achievable with phone-only GPS vs. what requires dedicated hardware.

• [High Priority] Driver Compliance Subdomain Extraction (DutyActivity):

  • Context: CrewDutyLog is structurally coupled to ServiceLeg → TourDeparture, blocking reuse of EU-561 driving/rest time tracking for public transport (Linienverkehr), chartering (Anmietverkehr), tachograph imports, and cross-tenant freelancer scenarios. EU-561 applies per driver, not per trip type — the compliance model must be business-area-agnostic.
  • Action: Implement the DutyActivity extraction per EU-561 research §6: (1) Create DutyActivity entity with source_type discriminator and duration-based fields, (2) build ComplianceEvaluator domain service in Backoffice evaluating all 6 EU-561 rules, (3) backfill from existing crew_duty_logs, (4) resolve the cross-tenant freelancer problem (§3.2). Phase 1 guard rails: do not add logic assuming service_leg_id presence, do not join through tour_departures for compliance, do not store compliance outcomes on CrewDutyLog.

8. Marketing & Growth

• [Medium Priority] IP Tracker — Automatic Company Profiling:

  • Context: Website visitors from bus tourism companies leave no trace unless they actively fill out a form. An IP-to-company reverse-lookup service (e.g., Clearbit Reveal, Leadfeeder, or Snitcher) can match visitor IPs to known company profiles in real time.
  • Action: Integrate an IP intelligence service into the marketing site / docs-hub. On each visit, resolve the visitor IP against a company database. If a match is found, automatically save the company profile (name, industry, size, location) to a leads table or CRM. Define: (1) which IP intelligence provider to use, (2) data model for captured company profiles, (3) deduplication logic for repeat visits, (4) GDPR compliance strategy (IP anonymization, legitimate interest basis).

• [Medium Priority] Bus Tourism Company Discovery & Booking Engine Crawler:

  • Context: Understanding the competitive landscape requires knowing which booking systems bus tourism companies currently use. Manually researching hundreds of operators is not scalable.
  • Action: Build tooling that automatically discovers bus tourism companies (via Google Maps API, industry directories like RDA, or web scraping) and crawls their websites to identify their booking engine. Detection strategies: (1) inspect page source for known booking widget signatures (e.g., Kuschick, Turista, Busreisen24, custom iframes), (2) check for characteristic URL patterns, script tags, or API calls, (3) classify results into categories (custom-built, known SaaS, no online booking). Store results in a structured dataset for sales outreach prioritization. Define: crawl frequency, rate limiting, robots.txt compliance, and output format (CSV / dashboard).

9. Förderung — Forschungszulage (FZulG)

• [High Priority] AP10–AP19 — Codebasis-Validierung & Plan-Adjustment für FZulG-Tauglichkeit:
  • Context: Der AP-Katalog (funding-work-packages.md) listet AP10–AP19 als 🟡 Kandidaten — Domänenartefakt vorhanden, aber Codebasis-Status (vorhanden / Phase 2 / nur Konzept) und tatsächliche Implementierungsausprägung sind nicht verifiziert. Risikobewertung in bsfz-ablehnungsrisiken.md hängt teils an Implementierungs-Details (insb. AP18 CRDT vs. Last-Write-Wins).
  • Action: Pro Kandidat-AP entscheiden: (a) AP entfällt mangels Codebasis-Substanz, (b) AP wird in einen anderen integriert (z.B. AP15 in AP3), (c) AP bleibt eigenständig. Bevorzugte Strategie: Wo der Implementierungs-Plan in den Docs (Domain Model, Protokolle, ADRs) noch flexibel ist, Plan an die FZulG-günstige Variante anpassen statt umgekehrt. Beispiel AP18: Wenn CRDT vs. Last-Write-Wins noch nicht entschieden, das Domain-Modell so schärfen, dass die CRDT-Variante als geplante Lösung dokumentiert wird (sofern technisch sinnvoll).
  • Sonderfall AP18: Binäre Entscheidung CRDT (Yjs/Automerge) vs. Last-Write-Wins-via-Hasura. Bei letzterem: AP18 streichen — kein F&E-Anteil.
  • Output: Status-Spalten in funding-work-packages.md aktualisieren (✅/🟡/⚪ → final), Risiko-Tabelle in bsfz-ablehnungsrisiken.md syncen, ggf. Vorhaben-Clustering in STRATEGY_public-funding.md anpassen.
  • Reihenfolge: Vor der eigentlichen BSFZ-Antragsverfassung (Phase 2 in funding-application-plan.md, W. 5–14). Ohne Validierung droht Stundenüberschätzung im Antrag → Glaubwürdigkeitsrisiko beim Gutachter.

10. Strategic — Repo Architecture

• [Low Priority] Evaluate "busflow-ceo" Repo Extraction:
  • Context: The monorepo contains strategic content (docs-hub, context-engine, presentations, architecture docs) alongside product code. As the team grows or the context-engine matures, extracting a dedicated "visionary workspace" repo could provide: (1) fine-grained access control over sensitive strategic content, (2) a clean separation of product engineering from strategic tooling, (3) a space for agentic-driven development experiments without polluting the product repo.
  • Trigger: Revisit this when either (a) the context-engine is battle-tested enough to serve as the documentation bridge back into the product repo, or (b) the team grows past ~5 people and role-based access control becomes a real need.
  • Action: If triggered, extract studio/docs-hub, packages/context-engine, studio/presentations, and select docs/ content into a new busflow-ceo repo. The context-engine would serve as the API layer feeding documentation back into the product monorepo.