fix: fix code smell

Author: udmada

README.md

@@ -8,26 +8,52 @@ Built for the Freightways take-home exercise.
 
 ```mermaid
 flowchart LR
-    API["Scan Event API"]
-    DB[("SQL Server\n(ParcelSummary)")]
-    STATE[("ProcessingState\ntable")]
-    DLQ["SQS Dead Letter Queue\n(manual redrive)"]
-
-    subgraph Worker Service
-        POLLER["ApiPollerWorker\n(BackgroundService)"]
-        PROCESSOR["EventProcessorWorker\n(BackgroundService)"]
+    subgraph exrernal[External Systems]
+        direction TB
+        API@{ shape: hex, label: "Scan Event API" }
     end
+    subgraph AWS
+        direction TB
+        subgraph sqs[SQS]
+            direction RL
+            DLQ@{ shape: das, label: "SQS DLQ<br/>(manual redrive)"}
+            QUEUE@{ shape: das, label: "SQS Main Queue<br/>(visibility timeout: 30s)" }
+        end
+        subgraph worker[Worker in ECS/Fargate]
+            direction LR
+            POLLER@{ shape: rounded, label: "ApiPollerWorker" }
+            PROCESSOR@{ shape: rounded, label: "EventProcessorWorker" }
+        end
+        subgraph db[SQL Server DB]
+            direction TB
+            PARCEL@{ shape: cyl, label: "ParcelSummary" }
+            STATE@{ shape: cyl, label: "ProcessingState" }
+        end
 
-    QUEUE[["SQS Main Queue\n(visibility timeout: 30s)"]]
+    end
+    exrernal ~~~ AWS
+    sqs & worker ~~~ db
+
+    API -->|"GET /v1/scans/scanevents<br/>?FromEventId=&Limit="| POLLER
+    STATE -->|"Read LastEventId<br/>on startup"| POLLER
+    POLLER -->|"Update LastEventId<br/>after batch sent"| STATE
+    POLLER -->|"SendMessageAsync<br/>(batch of ScanEvents)"| QUEUE
+    QUEUE -->|"ReceiveMessageAsync<br/>(long-poll 20s)"| PROCESSOR
+    PROCESSOR -->|"DeleteMessageAsync<br/>on success"| QUEUE
+    PROCESSOR -->|"MERGE upsert<br/>(idempotent)"| PARCEL
+    QUEUE -.->|"After 3 failures<br/>(maxReceiveCount)"| DLQ
+
+    classDef database stroke-width:2px
+    class PARCEL,STATE database
+
+    classDef queue stroke-width:2px
+    class QUEUE,DLQ queue
 
-    API -- "GET /v1/scans/scanevents\n?FromEventId&Limit" --> POLLER
-    STATE -- "Read LastEventId\non startup" --> POLLER
-    POLLER -- "SendMessageAsync\n(batch of ScanEvents)" --> QUEUE
-    POLLER -- "Update LastEventId\nafter batch sent" --> STATE
-    QUEUE -- "ReceiveMessageAsync\n(long-poll 20s)" --> PROCESSOR
-    PROCESSOR -- "MERGE upsert\n(idempotent)" --> DB
-    PROCESSOR -- "DeleteMessageAsync\non success" --> QUEUE
-    QUEUE -- "After 3 failures\n(maxReceiveCount)" --> DLQ
+    classDef api stroke-width:2px
+    class API api
+
+    classDef worker stroke-width:1px
+    class POLLER,PROCESSOR worker
 ```
 
 **Two decoupled `BackgroundService` workers:**
@@ -55,18 +81,37 @@ dotnet user-secrets set "ScanEventApi:BaseUrl" "https://your-api-host" --project
 dotnet run --project src/ScanEventWorker/ScanEventWorker.csproj
 ```
 
----
-
 ## Assumptions
 
 1. ~~Events are returned ordered by `EventId` ascending~~
 2. ~~`EventId` is monotonically increasing — querying `FromEventId=X` reliably returns all events with ID ≥ X~~
-3. The API returns an empty `ScanEvents` array when no more events exist (end-of-feed signal)
-4. Only one worker instance runs at a time (no distributed locking required)
+3. ~~The API returns an empty `ScanEvents` array when no more events exist (end-of-feed signal)~~
+   - guarded: `ApiPollerWorker` checks `Count == 0` and backs off
+4. ~~Only one worker instance runs at a time~~
+   - enforced: startup `Mutex` in `Program.cs` aborts a second instance
 5. `RunId` comes from the nested `User.RunId` field in the JSON response
+   - guarded: `null` coalesces to `string.Empty`
 6. `StatusCode` may be an empty string
-7. `PickedUpAtUtc` and `DeliveredAtUtc` are set on the **first** occurrence of their respective event types and are never overwritten by later events of the same type
-8. Unknown `Type` values are stored as-is in `ParcelSummary` without setting pickup/delivery timestamps
+   - guarded: `null` coalesces to `string.Empty`
+7. ~~`PickedUpAtUtc` and `DeliveredAtUtc` are set on the **first** occurrence of their respective event types and are never overwritten~~
+   - enforced: `??=` in `ParcelSummary` + `IS NULL` in SQL MERGE
+8. ~~Unknown `Type` values are stored as-is in `ParcelSummary` without setting pickup/delivery timestamps~~
+   - enforced: `switch` default + SQL `CASE`
+9. `CreatedDateTimeUtc` is the timestamp recorded as `PickedUpAtUtc`/`DeliveredAtUtc`
+   - the spec sample contains a `CreatedDateTimeUtc` field on each event
+   - no separate pickup/delivery timestamp field is defined
+10. First PICKUP/DELIVERY occurrence sets the timestamp permanently
+    - the spec is silent on correction or reversal events
+    - enforced: `??=` in `ParcelSummary` + `IS NULL` guard in SQL MERGE
+11. `Device` fields (`DeviceId`, `DeviceType`) and `User.UserId`/`User.CarrierId` from the API response are not persisted
+    - the spec only defines `ParcelSummary` columns
+    - extra fields are silently ignored
+12. `STATUS` events update the most-recent-event columns (`LatestType`, `LatestStatusCode`, etc.) but do not affect `PickedUpAtUtc`/`DeliveredAtUtc`
+13. Polling uses `FromEventId=LastEventId` (inclusive) rather than `LastEventId+1`
+    - the last processed event is re-fetched on every cycle to avoid missing events if IDs have gaps
+    - the idempotent MERGE absorbs the duplicate without side effects
+14. The event feed starts at `EventId=1`
+    - `ProcessingState` is seeded with `LastEventId=1` on first run d
 
 ## Potential Improvements
 

src/ScanEventWorker/Infrastructure/ApiClient/ScanEventApiClient.cs

@@ -67,7 +67,7 @@ public static Result<ScanEvent> MapToDomain(ScanEventDto dto)
                     : Result<ScanEvent>.Success(new ScanEvent(
                         new EventId(dto.EventId),
                         new ParcelId(dto.ParcelId),
-                        dto.Type,
+                        dto.Type.ToUpperInvariant(),
                         dto.CreatedDateTimeUtc,
                         dto.StatusCode ?? string.Empty,
                         dto.User?.RunId ?? string.Empty));

tests/ScanEventWorker.Tests/Infrastructure/ScanEventApiClientTests.cs

@@ -99,4 +99,15 @@ public void MapToDomain_UnknownType_StillSucceeds()
         Assert.True(result.IsSuccess);
         Assert.Equal("UNKNOWN_TYPE", result.Value.Type);
     }
+
+    [Fact]
+    public void MapToDomain_LowercaseType_NormalisedToUppercase()
+    {
+        var dto = new ScanEventDto { EventId = 1, ParcelId = 1, Type = "pickup", User = null };
+
+        Result<ScanEvent> result = ScanEventApiClient.MapToDomain(dto);
+
+        Assert.True(result.IsSuccess);
+        Assert.Equal("PICKUP", result.Value.Type);
+    }
 }