Functional View

Describes the system’s functional elements, their responsibilities, interfaces, and primary interactions. Based on the Rozanski & Woods functional viewpoint.

Functional Element Map

The platform groups its capabilities into thirteen functional elements, each with a single clear responsibility. This diagram maps the four actor types — Customer, Vendor, Platform Admin, and SmartVase Device — to the elements they interact with directly. Reading the lower half of the diagram shows the internal wiring: IoT Communication feeds Real-time Dispatch, Order Management triggers both Real-time Dispatch and Notifications, and the Cart → Order → Payment chain forms the customer purchasing spine.

flowchart TD
  subgraph Actors
    C["Customer\n(mobile / web)"]
    V["Vendor\n(shop / florist)"]
    A["Platform Admin"]
    D["SmartVase Device\n(IoT)"]
  end

  subgraph API["REST API — Functional Responsibilities"]
    AUTH["Authentication &\nTenant Resolution\n──────────────\nIssue dev-tokens\nValidate JWT\nExtract tenant claims"]
    DISC["Bouquet Discovery\n──────────────\nGeo-spatial search\nQR-code lookup\nFreshness scoring"]
    CART["Cart Management\n──────────────\nVendor-scoped cart\nAdd / remove items\nVendor-mismatch guard"]
    ORD["Order Management\n──────────────\nCreate order\nReserve bouquets (15 min)\nPayment confirmation\nMulti-line support"]
    PAY["Payment Processing\n──────────────\nStripe checkout\nWebhook handling\nRefunds"]
    VEND["Vendor Management\n──────────────\nOnboarding (shop / florist)\nBouquet CRUD\nEmployee CRUD\nOrder fulfillment"]
    VASE["Smart Vase Management\n──────────────\nRegistration & activation\nLocation tracking\nBouquet assignment"]
    IOT["IoT Communication\n──────────────\nMQTT subscribe/publish\nHeartbeat processing\nSensor data ingestion\nFreshness recalculation"]
    RT["Real-time Dispatch\n──────────────\nSignalR hub groups\nBouquet updates\nOrder status events\nView-count streaming"]
    NOTIF["Notifications\n──────────────\nFCM push dispatch\nIn-app notifications\nSubscription triggers"]
    ANA["Analytics\n──────────────\nVendor sales metrics\nBouquet performance\nPlatform KPIs"]
    CUST["Customer Profile\n──────────────\nFavourites\nSubscriptions\nSaved addresses\nDevice registration"]
    ADMIN["Platform Administration\n──────────────\nVendor approval/suspension\nVase administration\nCustomer management"]
  end

  C --> AUTH
  C --> DISC
  C --> CART
  C --> ORD
  C --> PAY
  C --> CUST
  V --> AUTH
  V --> VEND
  V --> VASE
  V --> ANA
  A --> AUTH
  A --> ADMIN
  A --> ANA
  D --> IOT

  IOT --> RT
  ORD --> RT
  ORD --> NOTIF
  VEND --> RT
  PAY --> ORD
  CART --> ORD
  DISC --> CART

Sub-domain Mapping

Functional Element	Business Sub-domain	Why it belongs there
Authentication & Tenant Resolution	Identity & Tenancy	Validates Keycloak JWT tokens and binds every subsequent operation to a VendorId, CustomerId, or platform-admin context
Bouquet Discovery	Customer Purchasing	Serves geo-spatial and QR-code-based bouquet search directly to the mobile/web customer
Cart Management	Customer Purchasing	Maintains the vendor-scoped shopping cart that bridges discovery to checkout
Order Management	Customer Purchasing / Vendor Order Fulfilment	Sits at the intersection — customers create orders, vendors fulfil them
Payment Processing	Payments	Owns all Stripe checkout sessions, webhook confirmation, and refund flows
Vendor Management	Vendor Management	Covers vendor onboarding (shop or florist), bouquet catalogue CRUD, employee management
Smart Vase Management	Vase & Bouquet Lifecycle	Handles registration, activation, location tracking, and bouquet assignment for IoT devices
IoT Communication	IoT / MQTT	Ingests MQTT heartbeats and sensor data; recalculates freshness scores based on device telemetry
Real-time Dispatch	IoT / MQTT + Customer Purchasing	Broadcasts bouquet updates (freshness, availability) and order status events via SignalR
Notifications	Customer Purchasing	Pushes FCM notifications to mobile devices on order and subscription events
Analytics	Vendor Management + Platform Administration	Aggregates sales and performance data scoped to a vendor or the whole platform
Customer Profile	Customer Purchasing	Persists favourites, subscriptions, saved addresses, and push-token registrations
Platform Administration	Platform Administration	Provides platform-wide vendor approval/suspension and vase/customer oversight

Functional Elements — Responsibilities

Element	Responsibility	Key Interfaces
Authentication & Tenant Resolution	Issue JWT dev-tokens; validate Keycloak OIDC tokens; extract vendor_id, vendor_type, customer_id from claims; set ITenantContextService	POST /auth/dev-token, Keycloak OIDC, TenantResolutionMiddleware
Bouquet Discovery	Geo-spatial bouquet search by radius; QR-code short-code lookup; freshness-score-based ranking	GET /bouquets, GET /bouquets/nearby, GET /bouquets/qr/{code}
Cart Management	Maintain vendor-scoped cart per customer; enforce single-vendor constraint; persist across devices	POST /cart/items, DELETE /cart/items/{id}, GET /cart
Order Management	Create multi-line orders from cart; reserve bouquets for 15 min; progress order through status machine	POST /orders, GET /orders/{id}, POST /orders/{id}/confirm-payment
Payment Processing	Initiate Stripe checkout session; handle webhooks; confirm or refund payments	Stripe SDK, POST /orders/{id}/confirm-payment, POST /webhooks/stripe
Vendor Management	Onboard Traditional Shop or Freelance Florist; manage bouquet catalogue; fulfil orders	POST /vendors, bouquet CRUD, employee CRUD, order fulfillment endpoints
Smart Vase Management	Register, activate, and locate vases; assign bouquets; track connection status	POST /smart-vases/register-by-technician, POST /smart-vases/{id}/activate
IoT Communication	Subscribe to MQTT topics; process heartbeats and sensor data; update vase connection status; recalculate bouquet freshness	MQTT vases/{id}/heartbeat, vases/{id}/sensor, MqttDeviceCommunicationService
Real-time Dispatch	Broadcast bouquet updates, order status changes, and view counts to connected clients via SignalR	BouquetHub, WebSocket groups radius:*, order:*, vendor:*
Notifications	Send FCM push notifications and in-app notifications triggered by order events and subscriptions	INotificationServiceClient, DeviceRegistration aggregate
Analytics	Aggregate vendor sales, bouquet performance, and platform-wide KPIs	GET /analytics/*, analytics query handlers
Customer Profile	Manage favourites, subscriptions, saved addresses, and device tokens	POST /favourites, POST /subscriptions, GET /customers/me
Platform Administration	Approve or suspend vendors; manage vases and customers platform-wide	Admin Portal, PATCH /vendors/{id}/status

Key Functional Constraints

• Multi-tenancy: every data operation is scoped by VendorId + VendorType; handlers call ITenantContextService.GetTenantContext() before any DB access.
• Cart vendor-lock: adding a bouquet from a different vendor than the current cart returns 409 vendor-mismatch.
• Bouquet reservation window: 15 minutes from order creation; expired reservations release bouquets back to Available.
• Single-vase bouquet: a SmartVase holds at most one Bouquet at a time (CurrentBouquetId).