Operational View

Describes how the system is operated, monitored, and maintained once deployed. Covers health checking, error handling, configuration management, and known operational gaps.

System Health Checks

In dev, Docker Compose polls each service’s dedicated health check. In production the platform runs as Fly.io apps (region fra) fronted by Cloudflare — Fly’s health checks poll each app. The API’s /health endpoint is the top-level signal for the application layer. Each infrastructure service exposes its own probe — PostgreSQL via pg_isready, Redis via redis-cli ping, MQTT via a broker probe (dev: Mosquitto mosquitto_sub; prod: HiveMQ Cloud, TLS 8883), and Keycloak via its /health/ready endpoint. All must report healthy for the platform to be considered fully operational; a failure in any one of them will block dependent service startup.

flowchart TD
  subgraph HealthChecks["Health Check Endpoints"]
    HC["GET /health\n(ASP.NET Core built-in)"]
    PGH["pg_isready -U postgres\n(postgres-dev)"]
    RH["redis-cli ping\n(redis-dev)"]
    MQH["mosquitto_sub -t $$SYS/broker/uptime\n(mqtt-dev)"]
    KCH["curl /health/ready\n(keycloak-dev)"]
  end

  ORCH["Health Poller\n(Docker Compose in dev / Fly.io in prod)"] -->|polls| HC
  ORCH --> PGH
  ORCH --> RH
  ORCH --> MQH
  ORCH --> KCH

Sub-domain Mapping — Health Checks

Request Error Handling Pipeline

flowchart TD
  REQ["Incoming HTTP Request"] --> GEX["GlobalExceptionMiddleware\n(catches all unhandled exceptions)"]
  GEX -->|unhandled exception| PD["ProblemDetails response\n500 Internal Server Error"]
  GEX --> AUTH["Authentication\n(401 Unauthorized if JWT invalid/missing)"]
  AUTH --> TENANT["TenantResolutionMiddleware\n(403 if claims missing for protected routes)"]
  TENANT --> BLACKLIST["TokenBlacklistMiddleware\n(401 if JTI revoked in Redis)"]
  BLACKLIST --> AUTHZ["Authorization Policies\n(403 if role/policy mismatch)"]
  AUTHZ --> RATE["RateLimiter\n(429 Too Many Requests)"]
  RATE --> IDEMP["IdempotencyMiddleware\n(replays cached response if key exists)"]
  IDEMP --> CTRL["Controller → MediatR Handler"]
  CTRL -->|Result.Error| MAP["Error string → HTTP status mapping\n(400 / 404 / 409 / 422 etc.)"]
  MAP --> RESP["HTTP Response"]

Sub-domain Mapping — Error Pipeline

Logging

The API uses ASP.NET Core’s built-in structured logging with RequestIdMiddleware injecting X-Request-ID on every request, enabling log correlation across services.

Log files are written to src/backend/FlowerShop.API/logs/ (mapped via Docker volume api_dev_logs).

Operational Runbook — Common Procedures

Starting the platform (dev)

# Start infrastructure
docker-compose -f docker/docker-compose.dev.yml up -d

# Start the API (hot reload)
cd src/backend/FlowerShop.API
dotnet watch run

# Start portals (separate terminals)
cd src/portals/FlowerShop.AdminPortal  && dotnet run   # :5001
cd src/portals/FlowerShop.VendorPortal && dotnet run   # :5002
cd src/portals/FlowerShop.CustomerApp  && dotnet run   # :5003

Running database migrations

cd src/backend/FlowerShop.Infrastructure
dotnet ef migrations add <MigrationName> --startup-project ../FlowerShop.API

cd ../FlowerShop.API
dotnet ef database update

Running tests

dotnet test    # runs 400+ test methods across 8 test projects

Checking Swagger

Navigate to http://localhost:8080/swagger — all 29 controllers and their endpoints are documented.

Sub-domain Mapping — Monitoring Signals

Known Operational Gaps (active stubs)

Monitoring Signals

Sub-domain Mapping — Operational Gaps

Security Operations

flowchart LR
  subgraph TokenLifecycle["JWT Token Lifecycle"]
    ISSUE["Keycloak issues JWT\n(sub, role, vendor_id, vendor_type, customer_id)"]
    USE["API validates JWT\nTenantResolutionMiddleware reads claims"]
    REVOKE["POST /auth/revoke\nJTI added to Redis blacklist"]
    CHECK["TokenBlacklistMiddleware\nchecks Redis on every request"]
  end

  ISSUE --> USE --> REVOKE --> CHECK --> USE

• Token revocation is synchronous and Redis-backed — revoked tokens are blocked on the next request.
• Multi-tenancy isolation is enforced at the MediatR layer via TenantValidationBehavior — handlers cannot accidentally access another tenant’s data.
• Rate limiting is applied globally via ASP.NET Core’s built-in RateLimiter middleware.
• Idempotency prevents duplicate orders even under concurrent client retries.