App-Internal Structure & Service Packages

Concrete conventions for Feature-Sliced Design (FSD) inside apps and the shared service packages defined in the Frontend Architecture.

Feature-Sliced Design (FSD)

Folder Layout per App

Every Quasar/Nuxt app under apps/ follows this internal structure. Features are grouped by Bounded Context to enforce DDD isolation while keeping the workspace as a single cohesive app shell.

apps/workspace/src/
├── app/              # App shell: router, layouts, global providers, plugin registration
├── pages/            # Route-level views — orchestrate widgets/features, no direct business logic
├── widgets/          # Large, self-contained UI blocks composed of multiple features
├── features/         # Grouped by Bounded Context
│   ├── backoffice/           # Context: Backoffice (Catalog & Planning)
│   │   ├── tours/            # [v0.1] Tour Templates, Departures, BoardingPoints
│   │   ├── pricing/          # [v0.1] CostingSheet → PriceMatrix generation
│   │   ├── operator-settings/ # [v0.1] Tenant config, Mollie keys, branding
│   │   ├── fleet/            # [v0.2] Vehicle inventory, TÜV/SP tracking
│   │   ├── staff/            # [v0.2] Crew management, qualifications
│   │   ├── dispatch/         # [v0.2] Manual driver/vehicle assignment
│   │   ├── ai-document-parsing/ # [v0.2] Magic Upload — PDF → structured tour
│   │   └── margin-calculator/   # [v0.2] Dynamic break-even & cost ingestion
│   ├── commerce/             # Context: Commerce (Sales & Fulfillment)
│   │   ├── bookings/         # [v0.1] Incoming orders, passenger lists, refunds
│   │   └── yield-manager/    # [v0.2] Dynamic pricing overrides
│   ├── operations/           # Context: Operations (Fleet Execution) — [v0.2]+
│   │   └── (deferred)
│   └── communications/       # Context: Communications (Messaging) — [v0.2]+
│       └── (deferred)
├── entities/         # Domain objects with UI representations
│   ├── tour/
│   ├── booking/
│   └── passenger/
└── shared/           # App-internal utilities (no business logic, no feature awareness)

Per-Slice Anatomy

Every features/<context>/<feature>/ folder uses the same internal layout:

features/backoffice/tours/
├── ui/               # Vue components scoped to this feature
│   ├── TourDrawer.vue
│   └── TourDetailPopup.vue
├── lib/              # Pure helpers scoped to this feature
│   └── formatters.ts
├── api/              # GraphQL operations scoped to this feature
│   ├── queries.ts
│   └── mutations.ts
├── types.ts          # Local interfaces (feature-scoped, not shared)
└── index.ts          # Public API — only export what other layers need

Import Rules & Domain Boundaries

Strict top-down dependency flow enforces internal boundaries. Violations are caught by ESLint (planned).

pages  →  widgets  →  features  →  entities  →  shared
  ↓          ↓           ↓            ↓           ✗
  OK         OK          OK           OK       (imports nothing from above)

• A widget may import from features, entities, and shared — never from another widget.
• A feature may import from entities and shared, never from another feature.
• An entity may import from shared only.

State Management & Cross-Domain Composition

To achieve our "App Shell / Modular Monolith" without breaking DDD:

• Zero Domain State Sharing: Features MUST NOT share domain-specific state with each other. For example, a Booking feature cannot read the Pinia state of a Trip feature.
• Cross-Cutting Application Concerns Only: Global App state (Pinia) is strictly reserved for cross-cutting application concerns (e.g., User Session, JWT/RBAC, multi-tenancy context, layout structure). Domain boundaries must stay completely "clean".
• UI Composition / Slots: The pages layer (in the App Shell) mounts components using layout slots. This allows a Backoffice page to render a Commerce interface element (like a refund button) seamlessly without the modules knowing about each other.
• Event Hand-offs: Cross-feature interactions use the Frontend Saga pattern (emitting global intent events) or URL handoffs, instead of direct import coupling.

NOTE

Future — Event Modeling on the Frontend: When the workspace reaches cross-feature widget composition (Dispatch Board, Omnichannel Inbox, Booking Overview), evaluate adopting Event Modeling patterns for the frontend event bus. This introduces typed Commands (user intents), domain Events (confirmed state changes), and Read Models (reactive projections) as the communication contract between features — replacing ad-hoc coupling with a structured, testable flow. Not needed for isolated CRUD features; becomes valuable once multiple widgets must react to the same state change.

All Apps (driver, passenger, booking-widget)

All apps now follow the consistent FSD tree structure, including the widgets directory where needed. Below is an illustrative example of the structure using the driver app features as an example:

apps/driver/src/
├── app/
├── pages/
├── widgets/
├── features/                   # Example features for driver app
│   ├── daily-assignments/      # Shift schedule, trip details
│   ├── passenger-checkin/      # QR scanner for Wallet passes/PDFs
│   ├── missing-passengers/     # Alert dispatcher about no-shows
│   ├── bordverkauf/            # Onboard POS (seat-linked food/beverage)
│   ├── receipt-scanner/        # AI OCR receipt capture
│   ├── vehicle-inspection/     # Digital pre-trip checklist
│   └── commercial-routing/     # Heavy-coach navigation
├── entities/
│   ├── trip/
│   ├── passenger/
│   ├── vehicle/
│   └── expense/
└── shared/

Note: The passenger and booking-widget apps also follow this identical FSD structure, but their internal features/ and entities/ folders will differ according to their respective domains.

---

Backend Architecture (NestJS)

The backend is built as a Modular Monolith using NestJS. To enforce Domain-Driven Design (DDD) and maintain strict boundaries, the NestJS application is internally structured around the four primary Bounded Contexts (Pillars).

Folder Layout per Pillar

apps/api/src/
├── app.module.ts           # Root module
├── shared/                 # Infrastructure, global filters, auth guards, common utilities
├── backoffice/             # Bounded Context: Backoffice
│   ├── backoffice.module.ts
│   ├── features/           # Handlers for Hasura Actions, Event Triggers
│   │   ├── import-tour/    # e.g., NestJS CQRS Command Handler
│   │   └── export-accounting/
│   └── index.ts
├── commerce/               # Bounded Context: Commerce
│   ├── commerce.module.ts
│   └── features/
│       └── process-checkout/
├── operations/             # Bounded Context: Operations
│   ├── operations.module.ts
│   └── features/
│       └── auto-dispatch/
└── communications/         # Bounded Context: Communications
    ├── communications.module.ts
    └── features/
        └── route-message/

This structure ensures that each backend module directly maps to its corresponding PostgreSQL schema (backoffice, commerce, operations, communications), keeping data access and business logic fully aligned.

---

Shared Packages: Abgrenzung

Package	Scope	Side Effects	Isomorphic	Example Content
packages/types	Validation schemas + inferred TS types	Minimal (Valibot runtime)	✅	TourSchema, BookingSchema, type Tour = z.infer<…>
packages/core	Pure utility functions	None	✅ Node.js + Browser	formatDate(), calculateDuration(), checkRestTimeViolation()
packages/[pillar]/*	Domain logic, grouped by pillar	Yes (API calls, file generation)	Varies	Wallet pass builder, price calculator
packages/api-client	HTTP/Supabase layer	Yes (network)	Browser only	supabaseClient, auth token refresh, typed fetch wrappers

packages/types — Schema Example

Schemas use Valibot (preferred over Zod for tree-shakeable, minimal bundle size). The system infers TypeScript types from schemas — never defining them separately.

// packages/types/src/tour.ts
import * as v from 'valibot';

export const TourSchema = v.object({
  id: v.pipe(v.string(), v.uuid()),
  title: v.string(),
  departure: v.date(),
  returnDate: v.date(),
  driverId: v.nullable(v.string()),
  vehicleId: v.nullable(v.string()),
  maxPassengers: v.pipe(v.number(), v.integer(), v.minValue(1)),
});

export type Tour = v.InferOutput<typeof TourSchema>;

packages/core — Isomorphic by Design

core functions run identically in Node.js (backend validation, Serverless Functions) and the browser (real-time Dispatcher warnings). No Vue, no DOM, no API calls — only Input → Calculation → Output.

// packages/core/src/compliance.ts
import type { Trip, Driver } from '@busflow/types';

export function checkRestTimeViolation(driver: Driver, newTrip: Trip): RestTimeResult {
  // Pure calculation — no side effects, no API calls
  // Used in workspace (real-time calendar warning) AND backend (final validation)
}

Designed for 100% test coverage with Vitest — pure functions are trivially testable in isolation.

---

Domain Packages (packages/[pillar]/*)

Each domain-specific package is its own module with an independent package.json. To strictly adhere to our bounded contexts, we group these packages by the Pillar they belong to. They encapsulate domain-specific business logic that both frontend apps and the NestJS backend consume.

IMPORTANT

Runtime vs. Capability: A domain package contains the capability (logic, templates, calculations). An app (or backend module) provides the runtime (HTTP endpoint, UI). Example: packages/commerce/wallet generates .pkpass files. The passenger app imports that package and serves the passes via an API endpoint. workspace could import the same package to generate batch exports for group bookings. The logic stays portable.

packages/commerce/wallet

Apple/Google Wallet pass generation and lifecycle management.

• .pkpass / Google Pass JWT template rendering
• Pass update payloads (gate changes, delays)
• Consumers: booking-widget (post-checkout "Add to Wallet"), passenger (display & update passes)

packages/communications/notifications

Outbound communication abstraction.

• WhatsApp template builder (via 360dialog / Twilio)
• Push notification payload composition
• Channel routing logic (WhatsApp vs. email vs. push)
• Consumers: workspace (dispatcher sends updates), driver ("Missing Passengers" alert), passenger (live updates)

packages/backoffice/pricing

Deterministic price calculation engine (Kalkulations-Engine). This is the mathematical core described in the Domain Model — Costing & Pricing Engine.

The package encapsulates the full pricing pipeline (cost aggregation → margin application → FX risk → DB validation → tax strategy → gross price → price matrix) and exposes it in two modes:

• Batch / Vorabkalkulation: Invoked asynchronously for an entire season's catalog. Produces CostingSheet records with complete price matrices. On finalization, emits a SeasonPricingFinalized event that pushes all computed gross prices into read-optimized Commerce caches (booking widget, agency portals).
• Real-time / Charter: Invoked synchronously from the CharterQuote flow. Calculates route-based costs (incl. Leerkilometer) via services/routing, applies B2B margins, and returns a fully costed quote within seconds.

Additional capabilities:

• Seasonal surcharges + seat category multipliers
• Upsell/add-on pricing (luggage, insurance)
• Discount rules (early bird, group, promo codes)
• FX risk buffer calculation for non-EUR procurement items
• Tax strategy resolution (standard VAT vs. § 25 UStG Margensteuer)
• Bidirectional yield management: accepts re-calculation requests when occupancy drops below threshold, computes minimum viable price (≥ break-even), and publishes PriceOverridePublished events
• Consumers: booking-widget (checkout totals, cached prices), workspace (tour pricing configuration, margin calculator, yield management UI)

packages/operations/compliance

Regulatory validation for fleet operations.

• EU VO 561/2006 driving-hours checker
• Rest-period validation & warnings
• max consecutive driving-day calculation
• Consumers: workspace (Copilot warnings during scheduling), driver (driving-time display)

packages/backoffice/pdf-parser

AI-powered document extraction pipeline.

• PDF → structured tour data extraction (via LLM)
• Confidence scoring per extracted field
• Side-by-side review data model (original vs. extracted)
• Consumers: workspace (Magic Upload) — single consumer, isolated for testability and independent iteration

packages/backoffice/accounting

Financial reconciliation and export engine.

• Cash-box reconciliation (POS sales vs. actual cash)
• Ledger mapping (Eigen- vs. Fremdleistungen, FiBu-Konten)
• DATEV-compliant CSV export generation
• Driver expense allocation to tour margins
• Consumers: workspace (Executive Control / GF View, end-of-month exports)

packages/operations/routing

Commercial vehicle routing and navigation data.

• Heavy-coach route calculation (bridge heights, weight limits, bus-only lanes)
• Zustiegsstellen pickup-sequence optimization
• Vehicle-profile-aware re-routing (e.g., 3-axle coach avoids low bridge)
• Consumers: driver (turn-by-turn navigation), workspace (dispatch route preview)

---

Package Index

Package	Path	Consumers
@busflow/types	packages/types/	All apps, all packages
@busflow/core	packages/core/	All apps, all packages
@busflow/commerce-wallet	packages/commerce/wallet/	booking-widget, passenger
@busflow/communications-notifications	packages/communications/notifications/	workspace, driver, passenger
@busflow/backoffice-pricing	packages/backoffice/pricing/	booking-widget, workspace
@busflow/operations-compliance	packages/operations/compliance/	workspace, driver
@busflow/backoffice-pdf-parser	packages/backoffice/pdf-parser/	workspace
@busflow/backoffice-accounting	packages/backoffice/accounting/	workspace
@busflow/operations-routing	packages/operations/routing/	driver, workspace