FlowerShop IoT Platform — Cross-Repo Contract Inventory

Purpose: Authoritative record of all integration touch-points between this repo and external systems (firmware, mobile app, portals, Keycloak, Stripe, Firebase FCM, RabbitMQ). Last scanned: 2026-03-21 Counterpart repos: flower-shop-firmware (ESP32), flower-shop-mobile (Flutter/React Native), portal front-ends (served from this repo), keycloak-config

Table of Contents

1. MQTT Topics
2. REST API Endpoints
3. SignalR Hub — BouquetHub
4. Domain / Integration Events (Event Bus)
5. Keycloak / JWT Claims & Auth Policies
6. Shared Config Keys & Environment Variables
7. Firebase FCM Push Notifications
8. Portal API Clients (Inbound REST)

1. MQTT Topics

Broker: Mosquitto — configured via MQTT__BrokerHost / MQTT__BrokerPort Counterpart repo: flower-shop-firmware (ESP32 smart vase firmware)

QoS default is AtLeastOnce (1) unless noted. Retain flag is false unless noted.

1a. Backend → Device (Publish)

status enum values: available, reserved, sold, removed theme enum values: default, elegant, modern, rustic type (alert) enum values: low_battery, connection_issue, sensor_malfunction, maintenance_required severity enum values: low, medium, high, critical

smartvase/{vendorId}/{deviceId}/commands payload variants

All command payloads share command (string) and timestamp (long). There is no separate /display topic — display updates ride the commands topic.

⚠️ Timestamp units differ: the display command (SendVaseDisplayCommandAsync) uses timestamp in seconds (ToUnixTimeSeconds); all generic commands (SendVaseCommandAsync, e.g. prepare_delivery) use timestamp in milliseconds (ToUnixTimeMilliseconds).

1. Display update (command: "updateDisplay") — nested payload object, timestamp in seconds:

{
  "command": "updateDisplay",
  "timestamp": 1712745600,
  "payload": {
    "status": "AVAILABLE",
    "price": 89.00,
    "currency": "PLN",
    "bouquetId": "b3f1a2c4-...",
    "qrCode": "https://app.findmyflowers.pl/Bouquets/Details/{bouquetId}?addToCart=true&vaseId={deviceId}",
    "message": "..."
  }
}

2. Generic command (flat payload; optional correlation_id; params merged at top level; timestamp in milliseconds):

{ "command": "restart|ping|configure|...", "timestamp": 1712745600000, "correlation_id": "..." }

3. Order-driven prepare_delivery (from OrderPaidVaseNotificationHandler on OrderPaidEvent; flat params, timestamp in milliseconds):

{
  "command": "prepare_delivery",
  "timestamp": 1712745600000,
  "display_mode": "delivery",
  "delivery_qr": "geo:<lat>,<lon>?q=<url-encoded-address>",
  "delivery_status": "PREPARING",
  "delivery_address": "<street>, <postalCode> <city>",
  "order_info": "ORDER #A1B2C3D4",
  "customer_id": "<customerId>"
}

display_mode / delivery_qr / delivery_status / delivery_address are present only for delivery orders that have a generated delivery QR code; order_info and customer_id are always present.

1b. Device → Backend (Subscribe)

Heartbeat payload schema (Device → Backend):

{
  "device_id": "vase-001",
  "shop_id": "shop-42",
  "timestamp": 1234567890,
  "state": "online|offline",
  "wifi_rssi": -65,
  "free_heap": 45000,
  "uptime": 3600000,
  "bouquet_present": true,
  "bouquet_price": 89.99,
  "temperature": 22.5,
  "humidity": 65.0,
  "sensor_errors": []
}

Sensor data payload schema (Device → Backend):

{
  "temperature": 22.5,
  "humidity": 65.0,
  "distance": 25.0,
  "bouquet_present": true,
  "state": "active|idle",
  "bouquet_price": 89.99
}

2. REST API Endpoints

Base URL: http://localhost:8080 (dev) — https://api.findmyflowers.pl (prod) API version prefix: /api/v1/ Counterpart repos: flower-shop-mobile (mobile app), portals (served from this repo), firmware heartbeat endpoint

2a. Public / Anonymous Endpoints

2b. Customer Endpoints (Policy: CustomerAccess)

2c. Vendor Endpoints (Policy: VendorAccess)

2d. Platform Admin Endpoints (Policy: PlatformAdmin)

2e. Common Response Errors

3. SignalR Hub — BouquetHub

Hub URL: /hubs/bouquet Transport: WebSocket with exponential backoff reconnect (0s, 2s, 5s, 10s, 30s) Counterpart repos: flower-shop-mobile, portals (Admin/Vendor/Customer)

3a. Client → Server Methods

3b. Server → Client Events

status values for OrderStatusChanged: created, paid, preparing, ready_for_pickup, in_delivery, delivered, cancelled reason values for BouquetBecameUnavailable: sold, reserved, vase_offline, removed status values for VaseStatusChanged: online, offline, error

4. Domain / Integration Events (Event Bus)

Current implementation: InMemoryEventBus via MediatR (in-process) Planned implementation: RabbitMQEventBus — EP-09 (currently stub, events silently dropped) RabbitMQ connection: amqp://flowershop:dev123@localhost:5672/ (dev) Counterpart repos: None currently (all in-process); future: analytics service, notification worker

When RabbitMQ is wired, these events will become inter-service contracts.

4a. Bouquet Events

4b. Order Events

4c. SmartVase Events

4d. Vendor Events

4e. Employee Events

5. Keycloak / JWT Claims & Auth Policies

Counterpart repos: keycloak-config (realm configuration), flower-shop-mobile, portals

5a. JWT Claims Extracted by This Repo

5b. Auth Policies

5c. Keycloak Server Configuration (Dev)

External repos must configure the same realm name, client ID, and custom claim mappers (vendor_id, vendor_type, customer_id) in Keycloak.

5d. Google SSO / Just-In-Time Customer Provisioning

Customers may sign in with Google (configured as an Identity Provider in the flowershop realm; committed export docker/keycloak/flowershop-realm.json). On a first Google login the Keycloak user exists but the platform DB does not, and the token carries no customer_id claim. TenantResolutionMiddleware detects this case (token has email, no vendor_id, no existing customer_id, not an admin) and calls CustomerProvisioningService.EnsureCustomerProvisionedAsync, which:

1. Reads email, given_name, family_name from the validated token.
2. Creates a local Customer + User (idempotently — reuses an existing user matched by Keycloak id or email).
3. Writes customer_id back to Keycloak via KeycloakAdminClient.SetUserAttributesAsync, and assigns the User realm role — so subsequent tokens carry the claim natively.
4. Injects the customer_id claim into the current request principal, so the very first request is authorized without requiring a re-login.

Consequently: customer_id may be absent on the first Google token and is populated mid-request; Google emails are treated as verified (no separate email-verification step); a Google login auto-links to any existing account with the same verified email.

6. Shared Config Keys & Environment Variables

Counterpart repos: keycloak-config, flower-shop-firmware, deployment infrastructure

6a. .NET Configuration Keys (IConfiguration paths)

6b. Docker Compose Environment Variables

7. Firebase FCM Push Notifications

Interface: INotificationServiceClient Implementation status: STUB — pending EP-06 Counterpart repo: flower-shop-mobile (receives FCM tokens and push messages)

Device registration endpoint: POST /api/v1/notifications/devices — accepts { deviceToken, platform, appVersion? }

8. Portal API Clients (Inbound REST)

The three portals (served from this repo) consume the REST API above. This section records which endpoints each portal calls, for dependency tracing.

Admin Portal (FlowerShop.AdminPortal)

Vendor Portal (FlowerShop.VendorPortal)

Customer App (FlowerShop.CustomerApp)

Note: Customer App cart calls use legacy path format cart/{customerId}/... which does not match the current API controller route cart/... (tenant from JWT). This is a known EP-13 gap.

Known Stubs & Gaps (Contract Risk)